Pharmacy Orders
Manage pharmacy orders — view incoming orders (prescription-based and over-the-counter) and update their status as you process them.List Orders
Filter by status. Accepted values:
init, waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled.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.Inclusive lower bound on the order’s
created_at Unix timestamp (seconds). Orders created before this moment are excluded.Inclusive upper bound on the order’s
created_at Unix timestamp (seconds). Orders created after this moment are excluded.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.
Response
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.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).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.Pharmacy-specific mapping for this shop shipping method. When present, it includes
pharmacy_uid and shipping_method_identifier_for_pharmacy.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.Parcels recorded on this pharmacy order, ordered by
sequence_number. Always an array: [] when nothing has been recorded yet, never null. List, detail, status-update, and complete-order responses all include it, and the objects match data.shipments on pharmacy order webhooks.A cancelled parcel stays in the list. Its tracking_number and tracking_url are null, because that parcel is no longer in transit. Carrier booking IDs, label file paths, and shipment charges are not included.HTTPS tracking URL, when known. Prefer this for customer-facing tracking.
null on a cancelled parcel.true only when the parcel was booked against a carrier sandbox. Ignore test shipments for live fulfillment.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
uidis created for the same shop order.
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.
Get Order Details
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)
Detail Response Fields
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.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.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.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.
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.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
Eachorder_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 is0.
total_paid_amount rather than pharmacy_sku.price.
Payouts
Order detail responses include top-levelpayouts. Each entry uses the same shape as the Payouts endpoint.
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.projected for an indicative preview, or routed for a persisted split-payment route created after pharmacy order completion.Payment provider route identifier. This is populated for routed payouts when the provider returned an identifier, and
null for projected payouts.Unix timestamp when the split-payment route was created. This is
null for projected payouts and populated for routed payouts.Update Order Status
Request Body
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
Putting an Order On Hold
When you move an order intoon-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.
Group-wide API keys append
?pharmacy_uid=<pharmacy uid> to this URL. A key tied to a single pharmacy leaves the parameter off. Without the parameter, a group-wide key returns 400 with "This query parameter is required for group-wide API keys.".comment, or with a comment that is only whitespace, returns a 400 response with body:
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.
Refused Status Changes
When the order’s current state does not allow the status you sent, the API returns400 and says why. The order is left unchanged and no notification is published.
code; error is a description for the person reading the response and may be reworded.
Do not retry these requests: the same request is refused again until the order changes. Treat a
code you do not know as a refused status change. The complete order endpoint below answers a cancelled order the same way.
Complete Order
orders_write permission.
Request Body
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.
Response
tracking_links is sent, shipments includes the parcel created from the first link. tracking_url is that link and carrier_name is the carrier you sent. See shipments for every field.
Validation Error Response
Whentracking_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.