Skip to main content

​
Pharmacy Orders

Manage pharmacy orders — view incoming prescription orders and update their status as you process them.

​
List Orders

​
page
integer
default:"0"
Page number (0-indexed)
​
limit
integer
default:"50"
Number of items per page (max 200)
​
status
string
Filter by status (e.g., waiting for pharmacy, on-hold, in-progress, completed)
​
search
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.
​
pharmacy_uid
string
Required for group-wide API keys
GET /v1/external-pharmacy-api-v1/pharmacy_orders/

​
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": { ... },
        "invoice_address": { ... },
        "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

​
shop_order_name
string | null
Human-readable shop order name from the originating shop (e.g. #1234). null for orders without a linked shop order.
​
shop_shipping_methods
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.
​
shop_shipping_methods[].pharmacy_mapping
object | null
Pharmacy-specific mapping for this shop shipping method. When present, it includes pharmacy_uid and shipping_method_identifier_for_pharmacy.
​
shipping_costs_amount
integer | null
Shipping costs in cents, for example 499 for EUR 4.99. This value is separate from product line item prices.
​
shipping_costs_currency
string | null
ISO currency code for the shipping costs, for example EUR.
​
order.priority
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.

​
Get Order Details

GET /v1/external-pharmacy-api-v1/pharmacy_orders/{pharmacy_order_uid}
Returns the full order including patient data, doctor data, and prescription file (if available).

​
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
}

​
Update Order Status

PATCH /v1/external-pharmacy-api-v1/pharmacy_orders/{pharmacy_order_uid}/status

​
Request Body

{
  "status": "in-progress"
}
​
status
string
required
New order status. See the table below for accepted values.
​
comment
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

StatusDescription
waiting for pharmacyOrder is in your queue, waiting to be processed
pending reviewOrder is being reviewed
on-holdOrder is paused while the pharmacy and admin team clarify an issue
in-progressOrder is being prepared
ready_for_pickupOrder is packed and ready for pickup or shipping
cancelledOrder 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-v1/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-v1/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.
​
pharmacy_uid
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. 
curl -X PATCH "https://api.rxscale.com/v1/external-pharmacy-api-v1/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",
  "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"
}