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.create_prescription_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.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_priceis 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_pricediffers from the mapped method’s price, Shopify currently has no live rate under the mapped method’s title, or no mapping exists for yourdelivery_type. A shipping line is created with thedelivery_priceyou sent. Its name is the mapped Shopify shipping method’s name whenever a mapping exists — including when only the price differs — and is thedelivery_typeyou 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 nodelivery.delivery_priceis 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."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.
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.Checkout Types
Thecheckout_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, sendprepaid: 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 areserved_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
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 optionalwarnings 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 acode, 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:
prescriptions[].id:
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.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.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.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
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 acode. 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:
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.