Prescriptions & Treatments

Create checkout sessions for prescriptions or treatments. These endpoints handle prescription validation, checkout creation, and return a checkout URL or draft order for the patient to complete their purchase.

Create Prescription Checkout

Upload one or more signed prescriptions (as base64 PDFs) along with line items and patient data to create a checkout.

POST /v2/public-api/prescriptions/{shop_identifier}

string

required

Unique identifier for the shop

Required permission: create_prescription_checkout

Request Body

{
  "reserved_draft_order_id": "123",
  "prescriptions": [
    {
      "id": "my-prescription-001",
      "pdf_base64": "JVBERi0xLjQK..."
    }
  ],
  "lines": [
    {
      "sku_uid": "sku-456",
      "quantity": 1,
      "prescription_id": "my-prescription-001"
    }
  ],
  "patient_data": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "date_of_birth": 631152000,
    "gender": "male"
  },
  "buyerIdentity": {
    "email": "max.mustermann@example.com",
    "phone": "+4917612345678",
    "countryCode": "DE",
    "customerAccessToken": "shopify-customer-access-token"
  },
  "checkout_type": "draft_order",
  "prepaid": false,
  "external_order_id": "order-123",
  "delivery": {
    "delivery_type": "pickup",
    "delivery_price": 499
  },
  "transaction": {
    "transaction_id": "txn-123",
    "transaction_amount": 4299
  },
  "billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address1": "Hauptstraße 42",
    "city": "Berlin",
    "province": "",
    "country_code": "DE",
    "zip": "10115"
  },
  "shipping_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address1": "Hauptstraße 42",
    "city": "Berlin",
    "province": "",
    "country_code": "DE",
    "zip": "10115"
  }
}

Field	Type	Required	Description
`reserved_draft_order_id`	string	No	Shopify legacy DraftOrder ID returned by the product reservation endpoint. When present, RxScale updates that draft order instead of creating a new checkout
`prescriptions`	array	No	List of prescription objects with `id` and `pdf_base64`
`prescriptions[].id`	string	Yes	Your internal ID for this prescription (used to link line items). At most 255 characters
`prescriptions[].pdf_base64`	string	Yes	Base64-encoded PDF of the signed prescription
`lines`	array	No	Line items for the checkout
`lines[].sku_uid`	string	Conditional	RxScale SKU UID from the product catalog. At least one of `sku_uid` or `external_id` is required per line
`lines[].external_id`	string	Conditional	Your telemedicine provider product ID (`telemedicine_provider_data.external_id` from the product catalog). Resolved using the provider linked to the API key. When both identifiers are sent, `sku_uid` takes precedence
`lines[].quantity`	integer	Yes	Quantity to order
`lines[].prescription_id`	string	No	Links the line item to a prescription by its `id`
`patient_data`	object	Yes	Patient demographic data
`patient_data.first_name`	string	Yes	Patient first name
`patient_data.last_name`	string	Yes	Patient last name
`patient_data.date_of_birth`	integer	Yes	Date of birth as Unix timestamp
`patient_data.gender`	string	Yes	Patient gender (`male`, `female`, `divers`)
`buyerIdentity`	object	Conditional	Shopify cart buyer identity. Required when `checkout_type` is `draft_order_without_checkout_request`; used for `checkout_link` carts, draft-order checkout requests, and to overwrite email/phone on a reserved draft order
`buyerIdentity.email`	string	No	Buyer email address
`buyerIdentity.phone`	string	No	Buyer phone number
`buyerIdentity.countryCode`	string	No	Shopify country code for the buyer
`buyerIdentity.customerAccessToken`	string	No	Shopify Storefront customer access token. When provided with `checkout_type: "checkout_link"`, Shopify associates the cart with the customer’s account
`checkout_type`	string	No	Checkout type: `checkout_link`, `draft_order` (default), or `draft_order_without_checkout_request`
`prepaid`	boolean	No	Whether the order has already been paid externally. Defaults to `false` and is attached to Shopify order attributes as `prepaid=true` or `prepaid=false`. It does not change `checkout_type` behavior
`external_order_id`	string	No	Your external order identifier. When present, RxScale attaches it to Shopify order attributes as `external_order_id`, and treats it as unique per telemedicine provider (a second successful injection with the same value returns `409`). At most 255 characters
`delivery`	object	No	Delivery method for the order. See Shipping Method Mapping below
`delivery.delivery_type`	string	No	Your identifier for the shipping method (for example `"pickup"` or `"express"`). When an RxScale admin has mapped this value to one of the store’s Shopify shipping methods, the order’s shipping line carries that method’s name; it carries that method’s price too unless you send a different `delivery_price`. Without a mapping, a shipping line is created from this value and `delivery_price`. Matched exactly, including case and whitespace
`delivery.delivery_price`	integer	No	Shipping price in the smallest currency unit (e.g. `499` for €4.99). When it matches the mapped Shopify shipping method’s own price, that method’s price is used for the shipping line; when it differs, your price is used instead. When omitted, the mapped method’s price applies
`transaction`	object	No	Transaction metadata to attach to the Shopify order attributes
`transaction.transaction_id`	string	No	Transaction identifier to attach to the Shopify order attributes
`transaction.transaction_amount`	integer	No	Transaction amount to attach to the Shopify order attributes
`billing_address`	object	No	Billing address attached to the Shopify draft order. Ignored when `checkout_type` is `checkout_link`
`billing_address.first_name`	string	No	Recipient first name
`billing_address.last_name`	string	No	Recipient last name
`billing_address.address1`	string	No	Single-line street address including house number
`billing_address.city`	string	No	City
`billing_address.province`	string	No	State, province, or region. Populated for countries like IE; sent as an empty string for countries like DE
`billing_address.country_code`	string	No	ISO country code
`billing_address.zip`	string	No	Postal code
`shipping_address`	object	No	Shipping address attached to the Shopify draft order. Ignored when `checkout_type` is `checkout_link`
`shipping_address.first_name`	string	No	Recipient first name
`shipping_address.last_name`	string	No	Recipient last name
`shipping_address.address1`	string	No	Single-line street address including house number
`shipping_address.city`	string	No	City
`shipping_address.province`	string	No	State, province, or region. Populated for countries like IE; sent as an empty string for countries like DE
`shipping_address.country_code`	string	No	ISO country code
`shipping_address.zip`	string	No	Postal code

buyerIdentity.customerAccessToken only applies when checkout_type is checkout_link, because Shopify uses it on Storefront carts. It does not attach a customer account to Shopify draft orders.

Send buyerIdentity when using checkout_type: "draft_order_without_checkout_request". RxScale rejects the request without it because no Shopify checkout request is sent to collect customer details later.

Shipping Method Mapping

delivery.delivery_type is your own identifier for a shipping method. An RxScale admin can map each of your delivery_type values to one of the store’s Shopify shipping methods. When you send delivery, RxScale looks up a mapping for the exact value you sent — matching is case- and whitespace-sensitive, so "Express" and "express" are treated as different values — and one of three things happens:

A mapped Shopify shipping method is found, and delivery.delivery_price is absent or matches that method’s own price. The shipping line carries that method’s name and price. It appears in your Shopify admin as a custom shipping line — not the store’s own live rate object — even though the name and price match the mapped method exactly.
delivery.delivery_price differs from the mapped method’s price, Shopify currently has no live rate under the mapped method’s title, or no mapping exists for your delivery_type. A shipping line is created with the delivery_price you sent. Its name is the mapped Shopify shipping method’s name whenever a mapping exists — including when only the price differs — and is the delivery_type you sent only when no mapping exists.
No mapping exists for your delivery_type — or one exists but Shopify currently has no live rate under that method’s title (for example it was renamed or deactivated in Shopify) — and no delivery.delivery_price is supplied. No shipping line is added to the order.

delivery.delivery_type and delivery.delivery_price continue to be attached as Shopify order attributes exactly as before, regardless of which of the three outcomes above applies. This is additive — if your integration already reads these attributes, it keeps working unchanged.

Shipping method mapping only applies when checkout_type is draft_order or draft_order_without_checkout_request. With checkout_type: "checkout_link", RxScale returns a Shopify Storefront cart, which has no shipping line — the customer chooses their delivery option during Shopify’s own checkout.

Example: a mapped delivery type with no price override

curl -X POST "https://api.rxscale.com/v2/public-api/prescriptions/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "sku_uid": "sku-456",
        "quantity": 1
      }
    ],
    "patient_data": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "date_of_birth": 631152000,
      "gender": "male"
    },
    "delivery": {
      "delivery_type": "express"
    }
  }'

If your store has mapped "express" to a Shopify shipping method, the resulting order’s shipping line carries that method’s name and price (shown in your Shopify admin as a custom shipping line, not the store’s live rate). The checkout response is unaffected by which outcome applies — the resolved shipping line is visible on the Shopify draft order or order itself, not in this response:

{
  "status": "success",
  "prescriptions": []
}

Checkout Types

The checkout_type field controls how the order is created in Shopify:

Value	Description
`draft_order`	Creates a Shopify draft order and sends a checkout request to the customer (default)
`checkout_link`	Returns a Shopify checkout link for the customer to complete payment directly
`draft_order_without_checkout_request`	Creates a Shopify draft order without sending a checkout request to the customer. Requires `buyerIdentity` because customer details are not collected through a Shopify checkout request

If reserved_draft_order_id is present, checkout_type is ignored. RxScale stores the signed prescriptions and adds _prescription_uid metadata to the matching reserved draft-order line items (not order-level attributes). Matching is based on the Shopify variant resolved from sku_uid; duplicate sku_uid values are rejected because they are ambiguous. Keys starting with _ are private Shopify properties and are often hidden in the Shopify Admin UI — verify via the Admin GraphQL API if needed. When buyerIdentity.email and/or buyerIdentity.phone are provided (and non-empty), they overwrite the reserved draft order’s buyer contact details; empty values are ignored so existing contact details are never cleared. The request’s billing_address and shipping_address are forwarded to the draft order, with the patient’s name from patient_data filled into each address where none is supplied (Shopify draft orders have no separate customer-name field). The reserved draft order must belong to the telemedicine provider linked to the API key.

Example Request

curl -X POST "https://api.rxscale.com/v2/public-api/prescriptions/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reserved_draft_order_id": "123",
    "prescriptions": [
      {
        "id": "rx-001",
        "pdf_base64": "JVBERi0xLjQK..."
      }
    ],
    "lines": [
      {
        "sku_uid": "sku-456",
        "quantity": 1,
        "prescription_id": "rx-001"
      }
    ],
    "patient_data": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "date_of_birth": 631152000,
      "gender": "male"
    },
    "buyerIdentity": {
      "email": "max.mustermann@example.com",
      "phone": "+4917612345678",
      "countryCode": "DE",
      "customerAccessToken": "shopify-customer-access-token"
    },
    "prepaid": false,
    "external_order_id": "order-123",
    "delivery": {
      "delivery_type": "pickup",
      "delivery_price": 499
    },
    "transaction": {
      "transaction_id": "txn-123",
      "transaction_amount": 4299
    },
    "billing_address": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "address1": "Hauptstraße 42",
      "city": "Berlin",
      "province": "",
      "country_code": "DE",
      "zip": "10115"
    },
    "shipping_address": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "address1": "Hauptstraße 42",
      "city": "Berlin",
      "province": "",
      "country_code": "DE",
      "zip": "10115"
    }
  }'

Response

{
  "status": "success",
  "prescriptions": [
    {
      "id": "rx-001",
      "prescription_uid": "px-abc123"
    }
  ]
}

The response maps your prescription IDs to the RxScale prescription UIDs. Use these UIDs to query order status via the Orders endpoint. When reserved_draft_order_id is used, no new checkout or draft order is created. The existing reserved draft order is updated and can continue through the normal Shopify order and fulfillment process after payment.

Error Responses

Status Code	Description
`400`	The same `prescriptions[].id` appears more than once in the request payload
`409`	A `prescriptions[].id` or an `external_order_id` was already successfully accepted for this telemedicine provider. No new prescription, PDF, or order is created
`422`	A prescription PDF is not digitally signed (QES) and unsigned prescriptions are not allowed for your provider
`400`	The signature-validation service was unavailable, so the prescription signature could not be validated. No prescription or order is created — safe to retry

Duplicate prescriptions[].id:

{
  "code": "duplicate_prescription_injection",
  "error": "Duplicate prescription injection: prescription id(s) ['rx-123'] already submitted by provider your-provider (existing prescription(s) ['px-abc123']); no order created.",
  "duplicates": [
    {
      "id": "rx-123",
      "prescription_uid": "px-abc123",
      "order_uid": null
    }
  ]
}

Duplicate external_order_id (even when prescriptions[].id is new):

{
  "code": "order_already_exists",
  "error": "Duplicate external_order_id: 'order-123' already submitted by provider your-provider (existing prescription px-abc123); no order created.",
  "external_order_id": "order-123",
  "prescription_uid": "px-abc123",
  "order_uid": null
}

code matches the Management API order-intake duplicate response so retries can share the same handling. Use prescription_uid with the Orders endpoint when order_uid is still null (typical right after injection, before Shopify creates the order).

A prescriptions[].id or external_order_id is only blocked once it has been successfully accepted. If an earlier request failed (for example, it returned a 4xx/5xx before completing), resubmitting the same value is not blocked and is processed normally. This makes prescription injection safe to retry after a failed or uncertain request — a repeat submission of an already-accepted id returns 409 instead of silently creating a duplicate order, so it can be treated as an idempotent no-op rather than an error to alert on.

These checks apply to every prescription-injection path that shares this entrypoint, including provider-specific integrations (for example medcanonestop, dransay) and reserved draft-order updates (reserved_draft_order_id).

Create Treatment Checkout

Create a checkout for treatment-based orders (no prescription required).

POST /v2/public-api/treatments/{shop_identifier}

string

required

Unique identifier for the shop

Required permission: create_treatment_checkout

Request Body

{
  "lines": [
    {
      "sku_uid": "sku-789",
      "quantity": 1,
      "anamnesis_id": "anam-001"
    }
  ],
  "buyerIdentity": {
    "email": "max.mustermann@example.com",
    "phone": "+4917612345678",
    "countryCode": "DE",
    "customerAccessToken": "shopify-customer-access-token"
  },
  "checkout_type": "draft_order"
}

Field	Type	Required	Description
`lines`	array	Yes	Line items for the checkout
`lines[].sku_uid`	string	Yes	SKU UID from the product catalog
`lines[].quantity`	integer	Yes	Quantity to order
`lines[].anamnesis_id`	string	No	Anamnesis ID for linking to a patient questionnaire
`buyerIdentity`	object	Conditional	Shopify cart buyer identity. Required when `checkout_type` is `draft_order_without_checkout_request`; used for `checkout_link` carts, draft-order checkout requests, and to overwrite email/phone on a reserved draft order
`buyerIdentity.email`	string	No	Buyer email address
`buyerIdentity.phone`	string	No	Buyer phone number
`buyerIdentity.countryCode`	string	No	Shopify country code for the buyer
`buyerIdentity.customerAccessToken`	string	No	Shopify Storefront customer access token. When provided with `checkout_type: "checkout_link"`, Shopify associates the cart with the customer’s account
`checkout_type`	string	No	Checkout type: `checkout_link`, `draft_order` (default), or `draft_order_without_checkout_request`

buyerIdentity.customerAccessToken only applies when checkout_type is checkout_link, because Shopify uses it on Storefront carts. It does not attach a customer account to Shopify draft orders.

See Checkout Types above for details on each option.

Example Request

curl -X POST "https://api.rxscale.com/v2/public-api/treatments/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "sku_uid": "sku-789",
        "quantity": 1
      }
    ],
    "buyerIdentity": {
      "email": "max.mustermann@example.com",
      "phone": "+4917612345678",
      "countryCode": "DE",
      "customerAccessToken": "shopify-customer-access-token"
    }
  }'

Response

{
  "status": "success",
  "checkout_url": "https://shop.example.com/checkout/abc123"
}

Getting Started

External Pharmacy API

Management API

Scheduling API

Public API

Patient API

Anamnesis API

Webhooks

Guides

Prescriptions & Treatments

Prescriptions & Treatments

Create Prescription Checkout

Request Body

Shipping Method Mapping

Checkout Types

Example Request

Response

Error Responses

Create Treatment Checkout

Request Body

Example Request

Response

​Prescriptions & Treatments

​Create Prescription Checkout

​Request Body

​Shipping Method Mapping

​Checkout Types

​Example Request

​Response

​Error Responses

​Create Treatment Checkout

​Request Body

​Example Request

​Response

Prescriptions & Treatments

Create Prescription Checkout

Request Body

Shipping Method Mapping

Checkout Types

Example Request

Response

Error Responses

Create Treatment Checkout

Request Body

Example Request

Response