Skip to main content
A patient wants to stop paying. Which call you make decides whether they keep the treatment they already paid for, whether money goes back, and what happens on the next billing date. This page is the map from what the patient asked for to the call that does it, and to what you have to read afterwards to know it worked.

What you’ll do

1

Pick the action from what the patient wants

Stop billing now, stop at the end of the period, hold the plan for a while, or put money back. They are separate calls on separate objects, and only one of them puts money back.
2

Send it with a complete body

Cancel and refund both validate the body before they look the subscription or invoice up, so a 400 here tells you nothing about whether the id exists.
3

Read the subscription back

None of these calls returns a payment result. GET /v0.1/subscriptions/{provider_subscription_id} is how you learn what actually happened.
4

Handle the order separately

Billing and shipping are different lifecycles. The order’s side reaches you only as prescription webhook events (signed webhooks) — see Prescription events for anything already on its way.

Which call does what

Cancel and refund are separate calls on separate objects — a subscription and a single invoice. A patient who wants to stop paying and get money back for what they already paid needs both calls.

Recipe · Cancel now or at period end

DELETE /v0.1/subscriptions/{provider_subscription_id} takes a required body with two required fields. Both are validated before the subscription is looked up, so an incomplete body returns 400 even for an id that does not exist.
The Response tab is the published response schema for this route, read 2026-09-11; the two rejection tabs are bodies observed against staging on the same day. This cookbook sends no successful cancel. The rejections, in the order the endpoint applies them: The response to a valid call is the subscription, in the same shape as GET /v0.1/subscriptions/{provider_subscription_id} — not a payment result. That comes from the published response schema rather than from a measurement here; see Cancelling is a billing action under Gotchas, and What comes back below.
Check cancel-requires-cancel-at-and-prorate locks every rejection in the table above, including the 404 on an id that does not resolve. It sends no successful cancel, so the success response shape is reference-sourced, not measured.

Recipe · Pause for N cycles, and resume

POST /v0.1/subscriptions/{provider_subscription_id}/pauses holds the subscription without ending it. The published schema marks the request body required: false, and cycles is its only field:
Omitting cycles is not the same as sending {}. The published cycles description is explicit about it: “Positive integer, or null for an open-ended pause (clears any previously scheduled resume). Omit the field entirely, rather than sending an empty body, to leave an existing scheduled resume untouched.” The first three rows above are that reference text (read 2026-09-11); neither the empty body nor the omitted field was probed here, because every one of those calls pauses a real subscription. Only the 400 and the 404 are measured.
Resume with DELETE /v0.1/subscriptions/{provider_subscription_id}/pauses. Both calls return 404 “Subscription not found” for a subscription id that does not resolve.
status is unchanged by a pause — read paused and resumes_at instead, as the Gotcha below explains.
Locked by check pause-and-resume-shape.
Pause is the retention lever, not the cancel lever — Upsell and cross-sell covers it alongside billing portals and retention sessions.

Recipe · Refund an invoice

A refund is issued against one finalized invoice, not against a subscription and not against an order. Find the invoice first:
  • GET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=paid — the invoices of one subscription
  • GET /v0.1/invoices?email=<billing email>&status=paid — keyed by billing email, as subscription lookup is
Then POST /v0.1/invoices/{provider_invoice_id}/refunds. Send an Idempotency-Key header. It is the only call on this page that moves money, and the published reference documents the header on it as the way to “deduplicate retried requests with the same key and parameters instead of creating a second resource”, recommending “an opaque, randomly-generated value such as a UUID”. Generate the key once per refund you intend to issue and reuse that same value on every retry of it:
The header is optional to the endpoint and required by your own retry logic. The body validation runs in that order — an empty body complains about amount, an amount alone complains about reason, and only a complete body reaches the invoice lookup. A complete body against an invoice id that does not resolve returns 404 with the provider’s own words: “Failed to create stripe credit note: No such invoice: ’…’”. A successful refund returns a credit note: the published reference documents provider_credit_note_id, status (issued or void), amount, currency and a credit_note_pdf URL. That is the receipt to store against your own record of the refund — this cookbook checks the validation and the lookup, not a real refund against a paid invoice.
Check refund-needs-amount-and-reason locks the body validation order and the 404 on an invoice id that does not resolve. The Idempotency-Key header is read from the published reference for this endpoint; this cookbook’s harness sends no request headers of its own, so the header is documented here but not measured here.

What comes back

None of these calls returns a payment result. Each returns the object it acted on, so the state you need is in a second read: And read the state back afterwards: The subscription and its invoices are two separate calls, and both return 404 for an id that does not resolve — so a 404 here is not evidence that the cancel failed; it is evidence you are holding the wrong id.
Check cancelled-subscription-reads-are-separate-calls locks exactly that and no more: the two reads are separate calls, and both 404 on an id that does not resolve.

Gotchas

The cancel_at error body is not valid JSON. That one message embeds unescaped double quotes in itself, so JSON.parse throws on the whole response — and error.message, error.error_code and request_id cannot be read out of it. Both rejections that produce it are affected: a missing cancel_at and a cancel_at that is neither keyword nor number. Wrap the parse, fall back to the raw text, and log that text: for these two the request_id you would quote to support is only available as a substring. Every other rejection on this page carries error.message, error.error_code and request_id as ordinary JSON fields.
Locked by check cancel-at-error-body-is-not-parseable-json, and by the cancel-at-must-be-keyword-or-number step of cancel-requires-cancel-at-and-prorate.
A 400 from cancel or refund says nothing about the id. Both endpoints validate the body first. 400 means your body is wrong; 404 means the body was accepted and the subscription or invoice was not found. Do not read a 400 as “already cancelled”.
Retry a refund only under the same Idempotency-Key. A refund that times out or fails to reach you may still have been issued. Retrying it without the header — or under a fresh key — is a second request with the same parameters, and the published reference describes the header as what deduplicates such a retry “instead of creating a second resource”. Mint the key before the first attempt, store it with your record of the refund, and reuse it. Other write endpoints document the same header — check the published reference for whichever call you are about to retry.
Cancelling is a billing action. The published reference for DELETE /v0.1/subscriptions/{provider_subscription_id} returns the subscription and nothing else — the response is the subscription, not a payment result, and nothing in it says money moved (published; read from the request and response schemas, not measured by this cookbook). An order already with the pharmacy has its own lifecycle, and there is no partner read of it: what you see is the prescription webhook events (signed). Wait for prescription.cancelled — data.status cancelled with data.timestamps.cancelled_at set — before telling a patient a shipment has been stopped, and escalate with the event’s data.resource_id and your cancel’s request_id if it needs to be pulled back. The money side of the order is not on prescription events: there is no prescription refund event and no payment field on these events. Read whether money moved from the refund you issue with the call above (its credit note) and from the billing surface — invoice.paid / subscription.* (see Events) or GET /v0.1/invoices.
Pause does not change status. The published reference states that pausing leaves the subscription’s status as it was and that you should read paused and resumes_at instead, and that a subscription with an attached schedule cannot be paused (400). Both are from the reference; this cookbook checks the request shape and the 404 and 400 rejections above, not the behaviour on a live paid subscription.
prorate on cancel and amount on refund are independent. prorate: true asks the provider to prorate the final invoice; it does not return money already collected. Money already collected comes back only through a refund.

Payments and checkout

The happy path this interrupts: payment, the subscription, and the order the charting note creates

Upsell and cross-sell

Pause, billing portals and retention sessions as alternatives to cancelling

Prescription events

The order’s side of a cancel, delivered to your endpoint as signed webhooks