Prescriptions & Treatments

Create prescription and treatment checkouts via the Public API

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}

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": "[e-mail]",
    "phone": "[phone]",
    "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)
prescriptions[].pdf_base64	string	Yes	Base64-encoded PDF of the signed prescription
lines	array	No	Line items for the checkout
lines[].sku_uid	string	Yes	SKU UID from the product catalog
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
delivery	object	No	Delivery metadata to attach to the Shopify order attributes
delivery.delivery_type	string	No	Delivery type. The store owner maps this value to their own shipping methods
delivery.delivery_price	integer	No	Delivery price to attach to the Shopify order attributes
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.

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": "[e-mail]",
      "phone": "[phone]",
      "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 was already successfully accepted for this telemedicine provider. No new prescription, PDF, or order is created

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

A prescriptions[].id is only blocked once it has been successfully accepted. If an earlier request with that id failed (for example, it returned a 4xx/5xx before completing), resubmitting the same id 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.

This check applies 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}

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": "[e-mail]",
    "phone": "[phone]",
    "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.

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.

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": "[e-mail]",
      "phone": "[phone]",
      "countryCode": "DE",
      "customerAccessToken": "shopify-customer-access-token"
    }
  }'

Response

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