Pharmacy Orders

Manage pharmacy orders — view incoming orders (prescription-based and over-the-counter) and update their status as you process them.

List Orders

integer

default:"0"

Page number (0-indexed)

integer

default:"50"

Number of items per page (max 200)

string

Filter by status. Accepted values: init, waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled.

string

Search term. Case-insensitive substring match against shop order name (e.g. #1234), pharmacy order name, patient name, order UID, and pharmacy order UID.Matching on the shop order name is only active for pharmacies that have the shop order name enabled (see the breaking change note below). When it is disabled, searching by the shop order name returns no results; the other search fields are unaffected.

integer

Inclusive lower bound on the order’s created_at Unix timestamp (seconds). Orders created before this moment are excluded.

integer

Inclusive upper bound on the order’s created_at Unix timestamp (seconds). Orders created after this moment are excluded.

string

Required for group-wide API keys

GET /v1/external_pharmacy_api/pharmacy_orders/

Both date bounds are optional and may be used independently — send only start_date for “everything since”, or only end_date for “everything up to”. Both are inclusive, so an order created at exactly start_date or exactly end_date is included.

curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/?start_date=1735689600&end_date=1738368000&limit=100" \
  -H "X-API-Key: your-api-key"

Response

{
  "data": [
    {
      "uid": "po-abc123",
      "status": "waiting for pharmacy",
      "name": "#1001",
      "shop_order_name": "#1234",
      "external_status": "OPEN",
      "pharmacy": {
        "uid": "ph-xyz",
        "display_name": "City Pharmacy"
      },
      "order": {
        "uid": "ord-123",
        "delivery_address": {
          "first_name": "Max",
          "last_name": "Mustermann",
          "street": "Hauptstr.",
          "house_number": "1",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "Germany",
          "additional_address": null,
          "province": null
        },
        "invoice_address": {
          "first_name": "Max",
          "last_name": "Mustermann",
          "street": "Hauptstr.",
          "house_number": "1",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "Germany",
          "additional_address": null,
          "province": null
        },
        "priority": 5
      },
      "order_items": [
        {
          "uid": "oi-789",
          "amount": 1,
          "sku": {
            "uid": "sku-456",
            "display_name": "Medication X 100mg",
            "pzn": "12345678"
          },
          "total_paid_amount": 1299
        }
      ],
      "shop_shipping_methods": [
        {
          "uid": "shop-shipping-method-uid",
          "display_name": "DHL Standard",
          "external_id": "shopify-standard",
          "pharmacy_mapping": {
            "pharmacy_uid": "pharmacy-uid",
            "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
          }
        }
      ],
      "shipping_costs_amount": 499,
      "shipping_costs_currency": "EUR"
    }
  ],
  "totalRegistries": 42,
  "totalPages": 1
}

Order Response Fields

The documented fields are the core contract, not an exhaustive list. Pharmacy order list and detail responses are serialised directly from the underlying order model, so they can include additional fields beyond the ones documented here, and new fields can be added at any time without notice.Build your integration to ignore unknown fields rather than rejecting the response. Configure your JSON deserialiser to skip properties it does not recognise (for example @JsonIgnoreProperties(ignoreUnknown = true) in Jackson, or a non-strict schema in Pydantic/marshmallow). Only the fields documented on this page are covered by our compatibility guarantees — treat anything else as informational and do not depend on it.

string | null

Human-readable shop order name from the originating shop (e.g. #1234). For an order placed through an RxScale-hosted storefront it is the storefront’s order number (e.g. RXS-1001). null for orders without a linked shop order, and null whenever the shop order name is disabled for the owning pharmacy (see the breaking change note below).

Breaking change — shop_order_name is now off by default.shop_order_name is now controlled by a per-pharmacy setting that is disabled by default. While it is disabled, every order belonging to that pharmacy returns shop_order_name: null (in both the list and the order-detail responses), and the order can no longer be found by searching for its shop order name.Previously this field was always populated whenever a linked shop order existed. If your integration relies on shop_order_name — for display, reconciliation, or search — the shop can enable the shop order name itself for the affected pharmacy in the admin tool (the pharmacy’s detail page, under the Shop Order Name setting); no RxScale involvement is required. Once enabled, the field is populated and searchable again exactly as before.Do not treat a null shop_order_name as “no shop order” — it can also mean the setting is disabled. Use the order.uid / pharmacy order uid as your stable identifiers.

array

Shop shipping methods attached to the connected shop order. Each entry includes the shop method (uid, display_name, external_id) and the pharmacy-specific mapping when one has been configured.

object | null

Pharmacy-specific mapping for this shop shipping method. When present, it includes pharmacy_uid and shipping_method_identifier_for_pharmacy.

integer

Shipping costs in cents, for example 499 for EUR 4.99. Always an integer: 0 (never null) when there are no shipping costs. This value is separate from product line item prices. For prepaid orders it is your share of the shop order’s shipping — see Multiple pharmacy orders per shop order.

string

ISO currency code for the shipping costs, for example EUR.

integer

Priority hint for handling order sooner. Higher = more urgent. 0 means no special priority.

Shop shipping methods come from connected shop orders. Pharmacists can configure pharmacy-specific identifiers for each shop shipping method in the pharmacy tool settings. If no mapping exists yet, the API still returns the shop shipping method with pharmacy_mapping: null. After a pharmacist saves a mapping, future order responses include the configured shipping_method_identifier_for_pharmacy.

Multiple Pharmacy Orders per Shop Order

RxScale creates one pharmacy order per fulfillment order, not one per shop order. When a shop order is split into several fulfillment orders, you receive several pharmacy orders for it:

Each pharmacy order contains only the items of its own fulfillment order.
Each pharmacy order is created when its part of the shop order is ready to be sent to a pharmacy. Items that need a prescription are only sent after the prescription has been signed, so pharmacy orders for the same shop order can arrive hours apart.
All pharmacy orders of the same shop order share the same order.uid.
If an order is cancelled and sent to a pharmacy again, the cancelled pharmacy order remains and a new pharmacy order with a new uid is created for the same shop order.

For prepaid orders (prepaid: 1), the shop order’s shipping costs are split evenly across all of its pharmacy orders that are not cancelled, including pharmacy orders handled by other pharmacies. shipping_costs_amount is your share. It is recalculated each time the order is retrieved or sent to you, so the value can change when another pharmacy order for the same shop order is created or cancelled.

Use the pharmacy order uid as your key. It is a UUID and never changes. Do not use shop_order_name as a key — it is not unique:

All pharmacy orders of the same shop order share it.
The same name can occur in different shops.
It is null while the shop order name is disabled for your pharmacy (see the breaking change note above).

Get Order Details

GET /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}

Returns the full order including patient data, doctor data, and prescription file (if available).

doctor_data and prescription_file are null for orders that contain only over-the-counter (OTC) products — these orders have no prescription attached.

shop_order_name follows the same per-pharmacy setting here as in the list response — it is null while the setting is disabled (the default). See the breaking change note above.

Response (additional fields)

{
  "uid": "po-abc123",
  "shop_order_name": null,
  "patient_data": {
    "uid": "pat-123",
    "display_name": "Max Mustermann",
    "email": "max@example.com",
    "date_of_birth": "1990-01-15"
  },
  "doctor_data": {
    "uid": "doc-456",
    "display_name": "Dr. Schmidt"
  },
  "prescription_file": {
    "filename": "prescription_001.pdf",
    "content_base64": "JVBERi0xLjQK..."
  },
  "shop_shipping_methods": [
    {
      "uid": "shop-shipping-method-uid",
      "display_name": "DHL Standard",
      "external_id": "shopify-standard",
      "pharmacy_mapping": null
    }
  ],
  "shipping_costs_amount": 499,
  "shipping_costs_currency": "EUR",
  "prepaid": 1,
  "payouts": [
    {
      "status": "projected",
      "amount": 1299,
      "currency": "EUR",
      "component_type": "item_rest",
      "routing_description": "Medication X 100mg rest amount",
      "provider_route_id": null,
      "pharmacy_order_uid": "po-abc123",
      "pharmacy_order_name": "#1001",
      "pharmacy_order_created_at": 1711899000,
      "routing_created_at": null
    }
  ]
}

Detail Response Fields

integer

1 when the order has a prescription of type physical with the status signed or NON_QES_SIGNED (see Prescription Statuses) — a prescription for physical products that the patient already paid for at checkout, including shipping. Otherwise 0, for example for orders with only over-the-counter products.physical is the prescription type. It does not refer to a paper or handwritten signature.

string

ID of the patient profile. It is assigned once and never regenerated. RxScale keeps one patient profile per customer account in a shop, so the same person has a different uid in another shop or with another customer account. When duplicate patient profiles are merged, orders of the removed profile show the uid of the remaining profile.

string

First and last name from the patient profile, or an empty string if no name is set. The recipient in order.delivery_address can be a different person; no field indicates this.

string

Email address of the customer on this shop order, as entered at checkout. It is not unique and can be empty. When duplicate patient profiles are merged, orders of the removed profile show the most recent email address of the remaining profile, if it has one.

object | null

The doctor who signed the prescription. null when the order has no prescription signed by a doctor on RxScale — for example an order with only over-the-counter products.

string

ID of the doctor. It is stable for a doctor within an organisation; a doctor who works for several organisations has a different uid in each.

Line item pricing

Each order_items[] entry carries two prices:

pharmacy_sku.price — the pharmacy’s list price for the SKU, in cents, as an order-time snapshot (the price captured when the order was placed). It does not change if the pharmacy later updates its list price.
total_paid_amount — the gross amount paid at checkout for the line, in cents. It is filled for prepaid orders (prepaid: 1, see above) and for orders marked as paid in the Pharmacy Portal; otherwise it is 0.

For prepaid orders, reconcile against total_paid_amount rather than pharmacy_sku.price.

Payouts

Order detail responses include top-level payouts. Each entry uses the same shape as the Payouts endpoint.

array

Payout components for this pharmacy order where the requested pharmacy is the receiver. Paid physical-prescription orders return projected payout previews based on current order values and routing configuration. Completed orders return routed payouts once a persisted split-payment route exists.

string

projected for an indicative preview, or routed for a persisted split-payment route created after pharmacy order completion.

integer

Payout amount in cents.

string

ISO 4217 currency code, for example EUR.

string

The payout component, such as item_rest, item_markup, or shipping.

string | null

Human-readable description of the routed or projected component.

string | null

Payment provider route identifier. This is populated for routed payouts when the provider returned an identifier, and null for projected payouts.

string

UID of the related pharmacy order.

string | null

Human-readable pharmacy order name, for example #1001.

integer

Unix timestamp when the pharmacy order was created.

integer | null

Unix timestamp when the split-payment route was created. This is null for projected payouts and populated for routed payouts.

Actual routing only happens when the pharmacy order is completed. projected payouts are indicative, only shown for paid physical-prescription orders, and can change before completion. On completion the order leaves the projected set; it appears as routed only if a split-payment route was created. There is no persistent projected history after completion.

Update Order Status

PATCH /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}/status

Request Body

{
  "status": "in-progress"
}

string

required

New order status. See the table below for accepted values.

string

Free-text explanation for the status change. Required (and must be non-blank) when transitioning to on-hold from any other status — the comment becomes the description of the admin issue thread that is automatically opened for the on-hold. Ignored for all other status transitions.

Allowed Status Values

Status	Description
`waiting for pharmacy`	Order is in your queue, waiting to be processed
`pending review`	Order is being reviewed
`on-hold`	Order is paused while the pharmacy and admin team clarify an issue
`in-progress`	Order is being prepared
`ready_for_pickup`	Order is packed and ready for pickup or shipping
`cancelled`	Order was cancelled

Do not set completed through this endpoint. Use the dedicated complete order endpoint below so RxScale can finalize the order, reduce stock, and publish the related events.

Putting an Order On Hold

When you move an order into on-hold, you must include a comment describing why the order is being paused. RxScale opens an admin issue thread automatically and uses your comment as the thread description so the admin team has the context they need to follow up.

curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "on-hold",
    "comment": "Out of stock until 2026-06-01"
  }'

A request without a comment, or with a comment that is only whitespace, returns a 400 response with body:

{
  "error": {
    "comment": ["A comment is required when setting an order on hold"]
  }
}

Subsequent on-hold PATCH requests for an order that is already on-hold do not require a new comment — they are treated as idempotent re-sends.

Complete Order

PATCH /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}/complete_order

Completes the pharmacy order, reduces stock for the pharmacy SKUs on the order, and publishes order update notifications. Requires the orders_write permission.

string

Required for group-wide API keys

Request Body

{
  "tracking_links": [
    {
      "tracking_link": "https://tracking.example.com/parcel/123",
      "carrier": "DHL"
    }
  ]
}

tracking_links is optional. If provided, the first tracking link is forwarded with the shipment update. Allowed carrier values are DHL, DPD, UPS, Hermes, FedEx, and Other.

curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/complete_order" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_links": [
      {
        "tracking_link": "https://tracking.example.com/parcel/123",
        "carrier": "DHL"
      }
    ]
  }'

Response

{
  "uid": "po-abc123",
  "status": "completed",
  "name": "#1001",
  "external_status": "OPEN",
  "pharmacy": {
    "uid": "pharmacy-uid",
    "display_name": "Example Pharmacy"
  },
  "order_items": [
    {
      "uid": "oi-789",
      "amount": 1,
      "sku": {
        "uid": "sku-456",
        "display_name": "Medication X 100mg",
        "pzn": "12345678"
      }
    }
  ],
  "shop_shipping_methods": [
    {
      "uid": "shop-shipping-method-uid",
      "display_name": "DHL Standard",
      "external_id": "shopify-standard",
      "pharmacy_mapping": {
        "pharmacy_uid": "pharmacy-uid",
        "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
      }
    }
  ],
  "shipping_costs_amount": 499,
  "shipping_costs_currency": "EUR"
}

Validation Error Response

When tracking_links contains an unsupported carrier or an invalid tracking link, the API returns 400 with the validation error and the pharmacy summary so you can map the error back to the affected pharmacy. If the order is already completed, calling complete_order again remains idempotent only when no tracking data is sent; tracking links on an already-completed order are rejected with 400 so shipment details are not silently dropped.

{
  "error": {
    "tracking_links": {
      "0": {
        "tracking_link": ["Invalid tracking link"]
      }
    }
  },
  "pharmacy": {
    "uid": "pharmacy-uid",
    "display_name": "Example Pharmacy"
  }
}

Getting Started

External Pharmacy API

Management API

Scheduling API

Public API

Patient API

Anamnesis API

Webhooks

Guides

Pharmacy Orders

Pharmacy Orders

List Orders

Response

Order Response Fields

Multiple Pharmacy Orders per Shop Order

Get Order Details

Response (additional fields)

Detail Response Fields

Line item pricing

Payouts

Update Order Status

Request Body

Allowed Status Values

Putting an Order On Hold

Complete Order

Request Body

Response

Validation Error Response

​Pharmacy Orders

​List Orders

​Response

​Order Response Fields

​Multiple Pharmacy Orders per Shop Order

​Get Order Details

​Response (additional fields)

​Detail Response Fields

​Line item pricing

​Payouts

​Update Order Status

​Request Body

​Allowed Status Values

​Putting an Order On Hold

​Complete Order

​Request Body

​Response

​Validation Error Response

Pharmacy Orders

List Orders

Response

Order Response Fields

Multiple Pharmacy Orders per Shop Order

Get Order Details

Response (additional fields)

Detail Response Fields

Line item pricing

Payouts

Update Order Status

Request Body

Allowed Status Values

Putting an Order On Hold

Complete Order

Request Body

Response

Validation Error Response