Order Intake

If your organisation does not sell through Shopify, order intake lets you push orders into RxScale directly from your own sales channel — your own website, POS system, or any other system of record. Everything downstream (prescriptions, pharmacy routing, fulfillment) works exactly the same way it does for a Shopify order; only how the order gets into RxScale differs.

This is for your own integration, pushing orders into your own organisation. If you are a telemedicine provider integrating into one of RxScale’s customer shops, see the Public API instead.

Before You Start

Required permission: every endpoint on this page requires order:write on your API key.
A shop must exist first. Orders are created against a shop_identifier that RxScale configures for your organisation when the integration is set up. Contact your RxScale account manager if you don’t have one yet.
Order status for your own customers lives elsewhere. This page only covers pushing orders in. To check the status of an order as it moves through prescription review and pharmacy fulfillment, use GET /v1/management/orders — the read endpoints already documented on the Orders page.

Four Operations

Method	Endpoint	Effect
`POST`	`/orders`	Create an order, including at least one fulfillment and its items
`POST`	`/orders/{order_external_id}/fulfillments`	Add a new fulfillment to an existing order
`PATCH`	`/orders/{order_external_id}`	Update item-free order fields (addresses, priority, customer email, shipping cost)
`POST`	`/orders/{order_external_id}/fulfillments/{fulfillment_external_id}/cancel`	Cancel a fulfillment, while it is still cancellable

Fulfillments are immutable. There is no endpoint to change the items on a fulfillment once it is created. To change what is dispensed, cancel the fulfillment and create a new one with the corrected items — this also starts a fresh prescription for the new items.

Create an Order

POST /v1/management/orders

Required permission: order:write Creates an order together with its first fulfillment (or several fulfillments at once). Creation is strictly once per external_id — see Retries and Duplicate Requests below.

Request Body

Field	Type	Required	Description
`shop_identifier`	string	Yes	The identifier of your shop, as configured by RxScale
`external_id`	string	Yes	Your own unique id for this order. Creating an order with the same `external_id` twice is rejected — see below
`name`	string	No	A human-readable order name/number, shown in the RxScale back office. Defaults to `external_id`
`customer`	object	Yes	See Customer object
`delivery_address`	object	Yes	See Address object
`invoice_address`	object	No	See Address object. Defaults to `delivery_address` when omitted
`shipping_cost`	object	No	See Money object
`shipping_methods`	array of strings	No	Free-text shipping method labels (e.g. `["standard"]`)
`priority`	integer	No	A priority hint used for internal queueing
`on_hold`	boolean	No	When `true`, the order is created on hold and does not proceed to a doctor or pharmacy automatically. Defaults to `false`
`hold_comment`	string	No	A note explaining why the order is on hold. Only meaningful together with `on_hold: true`
`doctor_uid`	string	No	Pre-assign a specific RxScale doctor to review the order’s prescriptions
`pharmacy_uid`	string	No	Pre-assign a specific pharmacy for the whole order
`pharmacy_email`	string	No	An email address to notify alongside `pharmacy_uid`
`referral_scan_uid`	string	No	Attribution reference for a referral link scan that led to this order
`fulfillments`	array of objects	Yes	At least one. See Fulfillment object

Customer Object

Field	Type	Required	Description
`id`	string	Yes	Your own stable id for this customer. Reused across orders to recognise a returning customer
`email`	string	No	The customer’s email address

Address Object

Field	Type	Required	Description
`first_name`	string	Yes
`last_name`	string	Yes
`street`	string	Yes
`house_number`	string	Yes
`zip_code`	string	Yes
`city`	string	Yes
`country`	string	Yes	2-letter ISO country code (e.g. `DE`)
`additional_address`	string	No	Apartment number, care-of line, etc.
`province`	string	No	State/region, where applicable

Money Object

RxScale never accepts decimal or floating-point amounts — amounts are always integers in the currency’s minor unit (cents for EUR), the same convention used throughout the platform.

Field	Type	Required	Description
`amount`	integer	Yes	Amount in minor units, e.g. `1998` for €19.98
`currency`	string	Yes	3-letter ISO currency code (e.g. `EUR`)

Fulfillment Object

A fulfillment is a group of items that ships and is prescribed together. Most orders have one; an order with items from different pharmacies or with different readiness (e.g. one item ready to ship, one still pending a prescription) has several.

Field	Type	Required	Description
`external_id`	string	Yes	Your own unique id for this fulfillment
`items`	array of objects	Yes	At least one. See Item object
`destination_pharmacy_uid`	string	No	Route this fulfillment to a specific pharmacy, bypassing automatic pharmacy selection
`location_id`	string	No	An alternate way to steer pharmacy routing, when your integration maps to RxScale-configured locations rather than pharmacy UIDs directly
`prescriptions`	array of objects	No	Signed PDFs to upload inline. See Linking a Prescription

Item Object

Field	Type	Required	Description
`external_id`	string	Yes	Your own unique id for this line, unique across the whole order (not just this fulfillment)
`sku_reference`	string	Yes	The SKU’s variant identifier in your catalogue, as configured in RxScale
`product_reference`	string	No	The product identifier in your catalogue. Required whenever `sku_reference` alone does not uniquely resolve a product in your shop’s configuration — ask your RxScale contact if you’re unsure whether your catalogue needs this
`quantity`	integer	Yes	Must be at least `1`
`total_paid`	object	Yes	See Money object. This is the amount the customer paid for this line — RxScale holds product identity, you hold price truth
`prescription_uid`	string	No	Link to an existing signed prescription. See Linking a Prescription
`prescription_reference`	string	No	Link to a PDF uploaded inline on this fulfillment. See Linking a Prescription
`anamnesis_uid`	string	No	Link to a completed questionnaire response, for an RxScale doctor to review. See Linking a Prescription
`fulfillment_method`	string	No	A hint used to select the delivery type (e.g. shipping vs. pickup) when your shop has more than one configured

Linking a Prescription

A line item needs a prescription whenever its product requires one. There are four ways to satisfy that, and every line uses exactly one of them:

Over the counter -- no prescription needed

Leave prescription_uid, prescription_reference, and anamnesis_uid all unset. Only valid for products in your catalogue that are configured as not requiring a prescription.

Send to an RxScale doctor

Set anamnesis_uid to the uid of a completed questionnaire response for this customer. An RxScale doctor reviews it and issues the prescription; the order moves to waiting for doctor until they do.

Reference a prescription you already have

Set prescription_uid to the uid of a prescription that is already signed — for example, one your integration obtained earlier through another RxScale flow. The prescription must already belong to your organisation.

Upload a signed PDF inline

Add an entry to the fulfillment’s own prescriptions array: {"id": "your-reference", "pdf_base64": "..."}. The PDF is validated for a qualified electronic signature (QES) as part of the request — an unsigned or invalid PDF rejects the whole order, nothing is created. On the line item, set prescription_reference to the same id you used in prescriptions. RxScale turns the upload into a prescription and links it to the line automatically; from that point on it behaves exactly like the previous option.

{
  "external_id": "ff-1",
  "items": [
    {
      "external_id": "line-1",
      "sku_reference": "variant-123",
      "product_reference": "prod-123",
      "quantity": 1,
      "total_paid": { "amount": 4500, "currency": "EUR" },
      "prescription_reference": "rx-upload-1"
    }
  ],
  "prescriptions": [
    { "id": "rx-upload-1", "pdf_base64": "JVBERi0xLjQK..." }
  ]
}

A line cannot set both prescription_uid and prescription_reference — pick one. A prescription_reference that names no entry in this fulfillment’s own prescriptions array is rejected before anything is created.

Example Request

curl -X POST "https://api.rxscale.com/v1/management/orders" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_identifier": "my-shop",
    "external_id": "order-10231",
    "customer": {
      "id": "cust-4471",
      "email": "patient@example.com"
    },
    "delivery_address": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "street": "Hauptstraße",
      "house_number": "1",
      "zip_code": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "fulfillments": [
      {
        "external_id": "ff-1",
        "items": [
          {
            "external_id": "line-1",
            "sku_reference": "variant-123",
            "product_reference": "prod-123",
            "quantity": 2,
            "total_paid": { "amount": 1998, "currency": "EUR" }
          }
        ]
      }
    ]
  }'

Response (201 Created)

{
  "order_uid": "ord-abc123",
  "external_id": "order-10231"
}

Field	Type	Description
`order_uid`	string	The RxScale-assigned order UID. Use it with `GET /v1/management/orders/{order_uid}` to check on the order afterwards
`external_id`	string	Echoes the `external_id` you sent

Error Responses

Status	Code	Description
`400`	`sku_not_found`	One or more items reference a `sku_reference`/`product_reference` combination not in your catalogue. The response also includes `missing_item_ids`, the `external_id` of each offending line. No order is created
`400`	(none)	The request body failed validation (missing/invalid field, an invalid inline PDF, a `prescription_reference` that names no upload, etc.). The response’s `error` field describes what failed
`401`	(none)	Missing or invalid API key
`403`	(none)	Missing `order:write` permission
`404`	(none)	No shop found for `shop_identifier` in your organisation
`409`	`order_already_exists`	An order with this `external_id` already exists. The response body carries the existing order’s `order_uid` — see Retries and Duplicate Requests

When a request is rejected, nothing is created — not the order, not a prescription from an inline PDF, nothing. external_id stays free to retry with a corrected payload.

Retries and Duplicate Requests

Order creation is strictly once per external_id: POSTing the same external_id a second time always returns 409 with code: "order_already_exists", even if the first request’s response never reached you (a timeout, a dropped connection). The 409 body carries the existing order’s order_uid, so recovering from a lost response needs no follow-up call — just retry with the same payload and read order_uid off the error:

{
  "code": "order_already_exists",
  "error": "Order order-10231 already exists for shop my-shop",
  "order_uid": "ord-abc123"
}

Alternatively, the same information is available via a lookup:

curl -X GET "https://api.rxscale.com/v1/management/orders?shop_identifier=my-shop&shop_order_external_id=order-10231" \
  -H "X-API-Key: your-api-key-here"

This is the same List Orders endpoint already documented on the Orders page, filtered down to at most one result.

Add a Fulfillment

POST /v1/management/orders/{order_external_id}/fulfillments

string

required

Your external_id for the existing order

Required permission: order:write Adds a new fulfillment (and its items) to an order that already exists. The request body is a single Fulfillment object — not wrapped in an order. Use this when items in the same order become available at different times, or need to be split across pharmacies. A fulfillment external_id that already exists on this order is rejected: fulfillments cannot be changed once created, only cancelled and replaced.

Example Request

curl -X POST "https://api.rxscale.com/v1/management/orders/order-10231/fulfillments" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ff-2",
    "items": [
      {
        "external_id": "line-2",
        "sku_reference": "variant-456",
        "product_reference": "prod-456",
        "quantity": 1,
        "total_paid": { "amount": 2500, "currency": "EUR" }
      }
    ]
  }'

Response (201 Created)

{
  "order_uid": "ord-abc123",
  "external_id": "ff-2"
}

Error Responses

Status	Code	Description
`400`	`sku_not_found`	One or more items reference an unknown SKU. `missing_item_ids` lists the offending `external_id`s
`400`	(none)	The request body failed validation
`401`	(none)	Missing or invalid API key
`403`	(none)	Missing `order:write` permission
`404`	(none)	No order found for `external_id` in your organisation
`409`	`fulfillment_immutable`	A fulfillment with this `external_id` already exists on the order
`409`	`order_not_updatable`	The order is in a status that no longer accepts new fulfillments (for example, `waiting for pharmacy`). A completed order is the exception: adding a fulfillment to it reopens it automatically instead of returning an error

Update an Order

PATCH /v1/management/orders/{order_external_id}

string

required

Your external_id for the existing order

Required permission: order:write Updates order-level fields that are not tied to items. Items are never accepted here — they always arrive inside a fulfillment (see Add a Fulfillment); a request body containing an items key is rejected.

Request Body

All fields are optional; send only what you want to change.

Field	Type	Description
`delivery_address`	object	See Address object
`invoice_address`	object	See Address object
`priority`	integer
`customer_email`	string
`shipping_cost`	object	See Money object

Example Request

curl -X PATCH "https://api.rxscale.com/v1/management/orders/order-10231" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_address": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "street": "Hauptstraße",
      "house_number": "2",
      "zip_code": "10115",
      "city": "Berlin",
      "country": "DE"
    }
  }'

Response (200 OK)

{
  "status": "updated"
}

Error Responses

Status	Code	Description
`400`	(none)	The request body failed validation, or contained an `items` key
`401`	(none)	Missing or invalid API key
`403`	(none)	Missing `order:write` permission
`404`	(none)	No order found for `external_id` in your organisation
`409`	`order_not_updatable`	The order is in a status that no longer accepts updates (for example, already completed)
`409`	`address_locked`	You’re changing `delivery_address` or `invoice_address` on an order that already has an active pharmacy order. Addresses lock once a pharmacy is preparing the shipment

Cancel a Fulfillment

POST /v1/management/orders/{order_external_id}/fulfillments/{fulfillment_external_id}/cancel

string

required

Your external_id for the order

string

required

Your external_id for the fulfillment to cancel

Required permission: order:write Cancels a fulfillment. This is the only way to change what a fulfillment contains — cancel it, then add a new fulfillment with the corrected items.

Cancellation is only possible while the fulfillment’s prescription (if it has one) has not yet reached a final state, and while no pharmacy is actively processing it. Once a doctor signs or declines the prescription, or a pharmacy starts working the order, cancelling is refused.

Example Request

curl -X POST "https://api.rxscale.com/v1/management/orders/order-10231/fulfillments/ff-2/cancel" \
  -H "X-API-Key: your-api-key-here"

Response (200 OK)

{
  "status": "cancelled"
}

Error Responses

Status	Code	Description
`401`	(none)	Missing or invalid API key
`403`	(none)	Missing `order:write` permission
`404`	(none)	No order or fulfillment found for the given `external_id`s in your organisation
`409`	`prescription_already_finished`	The fulfillment’s prescription is already signed or declined and can no longer be cancelled
`409`	`fulfillment_locked_by_pharmacy_order`	A pharmacy is already actively processing this fulfillment

Where Order Status Lives

This page covers pushing orders into RxScale. To track an order after that — its status, which prescription is attached, which pharmacy order was created — use GET /v1/management/orders and GET /v1/management/orders/{order_uid}, already documented on the Orders page. If you are instead a telemedicine provider tracking orders you placed through the Public API, order status for that flow lives in the Public API — not here.

Getting Started

External Pharmacy API

Management API

Scheduling API

Public API

Patient API

Anamnesis API

Webhooks

Guides

Order Intake

Order Intake

Before You Start

Four Operations

Create an Order

Request Body

Customer Object

Address Object

Money Object

Fulfillment Object

Item Object

Linking a Prescription

Example Request

Response (201 Created)

Error Responses

Retries and Duplicate Requests

Add a Fulfillment

Example Request

Response (201 Created)

Error Responses

Update an Order

Request Body

Example Request

Response (200 OK)

Error Responses

Cancel a Fulfillment

Example Request

Response (200 OK)

Error Responses

Where Order Status Lives

​Order Intake

​Before You Start

​Four Operations

​Create an Order

​Request Body

​Customer Object

​Address Object

​Money Object

​Fulfillment Object

​Item Object

​Linking a Prescription

​Example Request

​Response (201 Created)

​Error Responses

​Retries and Duplicate Requests

​Add a Fulfillment

​Example Request

​Response (201 Created)

​Error Responses

​Update an Order

​Request Body

​Example Request

​Response (200 OK)

​Error Responses

​Cancel a Fulfillment

​Example Request

​Response (200 OK)

​Error Responses

​Where Order Status Lives

Order Intake

Before You Start

Four Operations

Create an Order

Request Body

Customer Object

Address Object

Money Object

Fulfillment Object

Item Object

Linking a Prescription

Example Request

Response (201 Created)

Error Responses

Retries and Duplicate Requests

Add a Fulfillment

Example Request

Response (201 Created)

Error Responses

Update an Order

Request Body

Example Request

Response (200 OK)

Error Responses

Cancel a Fulfillment

Example Request

Response (200 OK)

Error Responses

Where Order Status Lives