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.
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.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.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 subscriptionGET /v0.1/invoices?email=<billing email>&status=paid— keyed by billing email, as subscription lookup is
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 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
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.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.Related
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

