> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> View projected and routed pharmacy payout amounts

# Payouts

Use the payouts endpoint to review the amounts that are expected to be routed to your pharmacy for paid physical-prescription orders, and the amounts that were actually routed after completed orders.

The endpoint only returns payouts where the requested pharmacy is the payment receiver. With a single-pharmacy API key, this is your current pharmacy. With a group-wide API key, this is the pharmacy selected by `pharmacy_uid`.

<Warning>
  Actual payment routing happens only when the pharmacy order is completed. `projected` payouts are indicative previews for paid physical-prescription orders based on the current order values and routing configuration, and can change before completion. `routed` payout values are populated only after the completed order has a persisted split-payment route.
</Warning>

## List Payouts

```bash theme={null}
GET /v1/external-pharmacy-api-v1/payouts
```

Requires the `orders_read` permission.

<ParamField query="pharmacy_uid" type="string">
  Required for group-wide API keys. Single-pharmacy API keys are automatically scoped to their pharmacy.
</ParamField>

<ParamField query="status" type="string">
  Filter by payout status. Accepted values are `projected` and `routed`.
</ParamField>

<ParamField query="search" type="string">
  Search term. Matches `pharmacy_order_uid`, `pharmacy_order_name`, routed payout `provider_route_id`, and `routing_description`.
</ParamField>

<ParamField query="start_date" type="integer">
  Unix timestamp for the start of the date range. For `routed` rows, this filters by `routing_created_at`. For `projected` rows, this filters by `pharmacy_order_created_at`.
</ParamField>

<ParamField query="end_date" type="integer">
  Unix timestamp for the end of the date range. For `routed` rows, this filters by `routing_created_at`. For `projected` rows, this filters by `pharmacy_order_created_at`.
</ParamField>

<ParamField query="sort_by" type="string" default="pharmacy_order_created_at">
  Field used for sorting. Accepted values are `pharmacy_order_created_at`, `routing_created_at`, and `amount`.
</ParamField>

<ParamField query="sort_direction" type="string" default="desc">
  Sort direction. Accepted values are `asc` and `desc`.
</ParamField>

<ParamField query="page" type="integer" default="0">
  Page number (0-indexed).
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of items per page.
</ParamField>

### Statuses

| Status      | Description                                                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projected` | Indicative preview for a paid physical-prescription order based on current order values and routing configuration. This can change before the order is completed. |
| `routed`    | Persisted split-payment route created after pharmacy order completion. These values represent the routed amount recorded by RxScale.                              |

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/external-pharmacy-api-v1/payouts?pharmacy_uid=ph-xyz&start_date=1711843200&end_date=1714521599&page=0&limit=20" \
  -H "X-API-Key: your-api-key-here"
```

### Response

```json theme={null}
{
  "data": [
    {
      "status": "routed",
      "amount": 1299,
      "currency": "EUR",
      "component_type": "item_rest",
      "routing_description": "Medication X 100mg rest amount",
      "provider_route_id": "rt_abc123",
      "pharmacy_order_uid": "po-abc123",
      "pharmacy_order_name": "#1001",
      "pharmacy_order_created_at": 1711899000,
      "routing_created_at": 1711985400
    },
    {
      "status": "routed",
      "amount": 250,
      "currency": "EUR",
      "component_type": "item_markup",
      "routing_description": "Medication X 100mg markup",
      "provider_route_id": "rt_def456",
      "pharmacy_order_uid": "po-abc123",
      "pharmacy_order_name": "#1001",
      "pharmacy_order_created_at": 1711899000,
      "routing_created_at": 1711985400
    },
    {
      "status": "projected",
      "amount": 499,
      "currency": "EUR",
      "component_type": "shipping",
      "routing_description": "DHL Standard",
      "provider_route_id": null,
      "pharmacy_order_uid": "po-def456",
      "pharmacy_order_name": "#1002",
      "pharmacy_order_created_at": 1711981200,
      "routing_created_at": null
    }
  ],
  "totalRegistries": 3,
  "totalPages": 1
}
```

### Response Fields

<ResponseField name="data" type="array">
  Payout rows for the requested page.
</ResponseField>

<ResponseField name="data[].status" type="string">
  `projected` for indicative payouts on paid physical-prescription orders, or `routed` for persisted routes created after order completion.
</ResponseField>

<ResponseField name="data[].amount" type="integer">
  Payout amount in cents, for example `1299` for EUR 12.99.
</ResponseField>

<ResponseField name="data[].currency" type="string">
  ISO 4217 currency code, for example `EUR`.
</ResponseField>

<ResponseField name="data[].component_type" type="string">
  The payout component, such as `item_rest`, `item_markup`, or `shipping`.
</ResponseField>

<ResponseField name="data[].routing_description" type="string | null">
  Human-readable description of the routed or projected component.
</ResponseField>

<ResponseField name="data[].provider_route_id" type="string | null">
  Payment provider route identifier. This is populated for routed payouts when the provider returned an identifier, and `null` for projected payouts.
</ResponseField>

<ResponseField name="data[].pharmacy_order_uid" type="string">
  UID of the related pharmacy order.
</ResponseField>

<ResponseField name="data[].pharmacy_order_name" type="string | null">
  Human-readable pharmacy order name, for example `#1001`.
</ResponseField>

<ResponseField name="data[].pharmacy_order_created_at" type="integer">
  Unix timestamp when the pharmacy order was created.
</ResponseField>

<ResponseField name="data[].routing_created_at" type="integer | null">
  Unix timestamp when the split-payment route was created. This is `null` for `projected` payouts and populated for `routed` payouts.
</ResponseField>

<ResponseField name="totalRegistries" type="integer">
  Total number of payout rows matching the filters.
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available for the current `limit`.
</ResponseField>