Skip to main content

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.
string
required
Unique identifier for the shop
Required permission: create_prescription_checkout

Request Body

A prescription is linked to an order only through lines[].prescription_id. Set it on every line the prescription covers. A prescription that no line references is still stored and its id is used up — resubmitting that prescriptions[].id is refused with 409 — but the resulting order is not linked to it. A prescription_id that matches no prescriptions[].id in the same request is rejected with 400 before anything is stored.
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:
  1. 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.
  2. 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.
  3. 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.
The /medcanonestop endpoint resolves its shipping field through the same mapping, as its delivery_type. MedCanOneStop sends no separate shipping price, so RxScale uses what remains of totalGross after the products (price × quantity of each product) as its delivery_price: totalGross 18250 with products totalling 17250 gives a shipping price of 1000 (€10.00). When totalGross or a product’s price is missing, or totalGross is lower than the products’ total, no price is used, so outcome 1 or 3 applies. "shipping": "Abholung" (pickup) is resolved the same way: a pickup order has no delivery address, so Shopify offers no rate for it, and the shipping line carries the remaining price, normally 0. For a prepaid order (prepaid: 1), the shipping line is part of the amount booked as paid. The medcanonestop_shipping and medcanonestop_total_gross order attributes are attached as before.
Example: a mapped delivery type with no price override
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:

Discounts

Discounts on a draft order need two things: you ask for them in the request, and RxScale has enabled them for your account. If either is missing, no discount is applied. Ask your RxScale contact to have an option enabled.
What happens when an option is not enabled for your account: A discount code that Shopify cannot apply to the order, for example an expired code or one that does not cover the products, is skipped without an error. The order is created without that discount.
These rules apply to draft orders (draft_order, draft_order_without_checkout_request, and reserved draft orders). With checkout_type: "checkout_link" the customer pays in the regular store checkout: automatic discounts apply there, the customer can enter codes, and discountCodes is applied to the cart. apply_automatic_discounts and allow_discount_codes_in_checkout are ignored for checkout_link.
apply_automatic_discounts and allow_discount_codes_in_checkout cannot be combined with prepaid: true. Such a request is rejected with 400 and code: "discounts_not_supported_with_prepaid", because the amount you already collected would no longer match the order total. For the same reason discountCodes sent with prepaid: true are ignored: the order is created without them.
Gift cards cannot be applied to a draft order by the API. The customer redeems a gift card in the checkout.

Checkout Types

The checkout_type field controls how the order is created in Shopify:
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.

Prepaid Orders

If you collect payment from the patient yourself, send prepaid: true. By default that only annotates the Shopify order: the draft order stays unpaid and the patient still receives a payment request. RxScale can enable per-provider handling that completes the order as paid instead. This is configured by RxScale, not through the API — ask your RxScale contact to enable it for your provider. Once it is enabled, a request with prepaid: true:
  • books the Shopify order as paid, so no payment request is sent to the patient;
  • captures no money — the payment you already collected is not routed through the shop;
  • applies to checkout_type: "draft_order", draft_order_without_checkout_request, and requests carrying a reserved_draft_order_id.
checkout_type: "checkout_link" is unaffected: a checkout link exists so the patient can pay, so there is nothing to book as paid. Send a draft-order checkout type for prepaid carts. Nothing else changes: the response shape, the 409 duplicate rules and the webhooks are the same. A booked order cannot be returned to draft state, so send prepaid: true only when the payment really has been collected. The same handling applies to the provider-specific prescription-injection endpoints (for example /docnow24, /medcanonestop), where prepaid: 1 carries the same meaning. If the booking fails, the request answers 502, and the code says whether a retry is safe: The uncertain case keeps your submission on purpose: if the booking did go through, a retry would book a second paid order for the same cart, which cannot be undone.

Example Request

Response

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.

Warnings

A successful response can carry an optional warnings list. It is only present when there is something to report, so check for the key rather than for an empty list.
phone_not_forwarded means the prescription was accepted, but buyerIdentity.phone was not set as the contact phone number of the order: either it could not be converted to E.164, or Shopify rejected it as invalid. Correct the number on your side; the request does not need to be repeated.

Error Responses

Every error body carries a code, except the 422 below. Branch on it, not on the status: see Public API Reason Codes. A lines[].prescription_id that matches no uploaded prescription:
Duplicate prescriptions[].id:
Duplicate external_order_id (even when prescriptions[].id is new):
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 products a patient was offered after a questionnaire. No prescription is uploaded: where a product needs one, an RxScale doctor issues it after the order is paid. RxScale stores nothing for this request; the order arrives once the patient has paid.
string
required
Unique identifier for the shop
Required permission: create_treatment_checkout

Request Body

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.
pharmacy_uid is checked against your organisation when the checkout is created. Where the order goes is decided after payment. For the order to reach that pharmacy, it has to be connected to the shop, and a pharmacy that receives prescriptions by email needs its address as well, sent as a pharmacy_email entry in attributes. If one of the two is missing, the order may not go to that pharmacy.
The Discounts rules above apply to this endpoint as well. It has no prepaid field, so the restriction for prepaid orders does not come into play. No shipping line is added to the draft order.

Attributes

attributes on the order and on each line are passed to Shopify as they are and arrive with the order. A few keys change how RxScale processes the order, so this endpoint does not accept them from a caller. A request that carries one of them, on the order or on a line, is rejected with 400 and names the key:
  • _skip_validation
  • _rxscale_skip_validation
  • _doctor_uid
  • _rxscale_doctor_uid
Use the request fields instead of attributes where one exists: lines[].anamnesis_id rather than an _anamnesis_uid line attribute, and pharmacy_uid rather than a pharmacy_uid order attribute. The fields are checked against your organisation before the checkout is created, so a mistyped value is reported to you instead of being dropped later. When both are sent, the field wins.

Example Request

Response

checkout_url is where the patient pays: the cart’s checkout for checkout_link, the draft order’s invoice page for draft_order and draft_order_without_checkout_request. With draft_order Shopify also sends this link to buyerIdentity.email.

Error Responses

Every error body carries a code. Branch on it, not on the status: see Public API Reason Codes. A request that is rejected with one of these codes, or by validation, creates nothing in the shop. With checkout_type: "draft_order" the draft order is created first and the invoice mail is sent second. If the mail cannot be sent, the request fails although the draft order exists. Always send buyerIdentity.email with this checkout type, and do not retry a request that failed this way unchanged: every attempt creates another draft order. A refused attribute key:
An anamnesis_id that does not belong to your organisation:

Moving from the Legacy Treatments Endpoint

The request body of the previous treatments endpoint is accepted here, so most integrations change the URL and the points below. Discounts are new: the previous endpoint never applied a discount to a draft order. See Discounts.