> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel, pause and refund

> Cancel now or at period end, pause for N cycles and resume, refund an invoice — which call does what to the subscription and the order.

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

| The patient wants | The call | The body | Effect |
| - | - | - | - |
| To stop immediately | `DELETE /v0.1/subscriptions/{provider_subscription_id}` | `cancel_at: "now"`, `prorate` | Cancels with the provider straight away; `prorate` decides whether the final invoice is prorated |
| To keep what they paid for and not renew | same call | `cancel_at: "period_end"`, `prorate` | Sets the cancel-at-period-end flag; billing stops at the end of the current period |
| To stop on a specific date | same call | `cancel_at: <future unix seconds>`, `prorate` | Cancels at that instant. The timestamp must be in the future |
| To take a break, then come back | `POST /v0.1/subscriptions/{provider_subscription_id}/pauses` | `cycles` | Stops invoicing for N billing cycles |
| To come back early | `DELETE /v0.1/subscriptions/{provider_subscription_id}/pauses` | — | Resumes |
| Their money back | `POST /v0.1/invoices/{provider_invoice_id}/refunds` | `amount`, `reason` | Issues a credit note against one finalized invoice |

**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.

| Field | Required | Values |
| - | - | - |
| `cancel_at` | yes | `"now"`, `"period_end"`, or a future Unix timestamp in **seconds** |
| `prorate` | yes | Boolean. The string `"false"` is rejected — it must be a real boolean |
| `cancellation_details` | no | `comment` (free text) and `feedback` (`customer_service`, `low_quality`, `missing_features`, `other`, `switched_service`, `too_complex`, `too_expensive`, `unused`) |

```bash curl theme={null}
curl -X DELETE https://api-staging.openloophealth.com/v0.1/subscriptions/<provider_subscription_id> \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "cancel_at": "period_end",
    "prorate": false,
    "cancellation_details": { "comment": "Switching plans", "feedback": "switched_service" }
  }'
```

```json Response — the subscription, nested under data.subscription (reference) theme={null}
{ "data": { "subscription": { "provider_subscription_id": "sub_...", "status": "active",
                              "cancel_at_period_end": true, "items": [ ... ] } },
  "request_id": "..." }
```

```json 400 — body rejected before the lookup theme={null}
{ "error": { "message": "prorate is required and must be a boolean",
             "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

```json 404 — complete body, id does not resolve theme={null}
{ "error": { "message": "Subscription not found", "error_code": "NOT_FOUND" },
  "request_id": "..." }
```

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:

| You sent | Status | Message |
| - | - | - |
| No `cancel_at` | `400` | *cancel\_at is required and must be "now", "period\_end", or a future unix timestamp (integer seconds)* |
| `cancel_at` that is neither keyword nor number | `400` | the same message |
| `cancel_at` in the past | `400` | *cancel\_at must be a future unix timestamp (seconds)* |
| No `prorate`, or a non-boolean | `400` | *prorate is required and must be a boolean* |
| A complete body, an id that does not resolve | `404` | *Subscription not found* |

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.

> [!TIP]
>
> 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:

| `cycles` | Meaning |
| - | - |
| A positive integer | Pause for that many billing cycles |
| `null` | Open-ended pause; also clears any resume already scheduled |
| Field omitted entirely | Pause, leaving an existing scheduled resume untouched |
| `0`, or a non-integer such as `2.5` | `400` — *"cycles must be a positive integer when provided"* |

> [!NOTE]
>
> **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.

```bash curl theme={null}
# pause for two cycles
curl -X POST https://api-staging.openloophealth.com/v0.1/subscriptions/<provider_subscription_id>/pauses \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{ "cycles": 2 }'

# resume
curl -X DELETE https://api-staging.openloophealth.com/v0.1/subscriptions/<provider_subscription_id>/pauses \
  -H "authorization: Bearer $TOKEN"
```

```json Response — the subscription, nested under data.subscription (reference) theme={null}
{ "data": { "subscription": { "provider_subscription_id": "sub_...", "status": "active",
                              "paused": true, "resumes_at": "..." } },
  "request_id": "..." }
```

```json 400 — cycles: 0, or a non-integer theme={null}
{ "error": { "message": "cycles must be a positive integer when provided",
             "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

```json 404 — id does not resolve (both pause and resume) theme={null}
{ "error": { "message": "Subscription not found", "error_code": "NOT_FOUND" },
  "request_id": "..." }
```

`status` is unchanged by a pause — read `paused` and `resumes_at` instead, as the Gotcha below
explains.

> [!TIP]
>
> 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:

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/invoices/<provider_invoice_id>/refunds \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: $REFUND_KEY" \
  -d '{ "amount": 4500, "reason": "product_unsatisfactory", "description": "Returned unopened" }'
```

```json Response — a credit note (reference) theme={null}
{ "data": { "provider_credit_note_id": "cn_...", "status": "issued",
            "amount": 4500, "currency": "usd",
            "credit_note_pdf": "https://..." },
  "request_id": "..." }
```

```json 400 — empty body: amount is checked first theme={null}
{ "error": { "message": "amount must be a positive integer in cents",
             "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

```json 404 — complete body, invoice does not resolve theme={null}
{ "error": { "message": "Failed to create stripe credit note: No such invoice: 'in_...'",
             "error_code": "NOT_FOUND" },
  "request_id": "..." }
```

The header is optional to the endpoint and required by your own retry logic.

| Field | Required | Notes |
| - | - | - |
| `Idempotency-Key` (header) | no, but send it | Opaque random value such as a UUID, held constant across every retry of the same refund |
| `amount` | yes | Positive integer, **in cents**. `0` is rejected |
| `reason` | yes | Exactly one of `duplicate`, `fraudulent`, `order_change`, `product_unsatisfactory` |
| `description` | no | Free text; becomes the credit note memo |

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.

> [!TIP]
>
> 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:

| Field | Meaning | You key on it for |
| - | - | - |
| `data.subscription.status` | `active`, `canceled`, `past_due`, … — **unchanged by a pause** | Whether a cancel took effect |
| `data.subscription.cancel_at_period_end` | Set by `cancel_at: "period_end"`; billing stops at the end of the period | Telling a scheduled cancel from an immediate one |
| `data.subscription.paused`, `data.subscription.resumes_at` | The pause state and when it lifts | Showing a paused patient what happens next |
| `data.provider_credit_note_id`, `credit_note_pdf` | The receipt a successful refund issues | Your own record of the refund |
| `error.error_code` | `VALIDATION_ERROR` on a `400`, `NOT_FOUND` on a `404` | Telling a bad body from a bad id — they mean different things here |
| `request_id` | Present on every response, success or failure | Escalation. See the `cancel_at` Gotcha: on two rejections it is only available as a substring |

And read the state back afterwards:

| Read | What it tells you |
| - | - |
| `GET /v0.1/subscriptions/{provider_subscription_id}` | The resulting `status`, and — for a pause — `paused` and `resumes_at` |
| `GET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=open` | An unpaid final or prorated invoice left behind by the change |
| Prescription webhook events (signed, not a read) | The order's own lifecycle: `prescription.cancelled` carries `data.status` `cancelled` and `data.timestamps.cancelled_at`. Refunds are not a prescription event — read the money side from the billing surface (the refund above, `GET /v0.1/invoices`). There is no partner read of an order — see *Prescription events* |

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.

> [!TIP]
>
> 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

> [!WARNING]
>
> **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.

> [!TIP]
>
> 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`.

> [!WARNING]
>
> **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".

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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`.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> `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

> [card] [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
>
> The happy path this interrupts: payment, the subscription, and the order the charting note creates

> [card] [Upsell and cross-sell](https://openloop.mintlify.site/cookbook/upsell-and-cross-sell.md)
>
> Pause, billing portals and retention sessions as alternatives to cancelling

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> The order's side of a cancel, delivered to your endpoint as signed webhooks


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.