Supplies

A supply is months of medication a partner sold on its own checkout and handed to a clinic's storefront: one supply per paid invoice, so a plan's first term and each renewal are separate supplies of the same subscription. You never create or change one through this API. Your handoff opens it, and it ends when your subscription is cancelled, when a clinician declines a monthly check-in after the first month, or when the clinic stops the plan from its console.

Supplies exist in live mode only. Reading one needs orders:read.

Reading a supply

GET /v1/supplies/{id} reads one, by the sup_… id a supply.stopped.v1 event names.

curl "https://api.cuvo.co/v1/supplies/sup_8c1d2e3f-4a5b-4c6d-8e7f-901a2b3c4d5e" \
  -H "Authorization: Bearer cuvo_sk_live_…"

{
  "id": "sup_8c1d2e3f-4a5b-4c6d-8e7f-901a2b3c4d5e",
  "status": "stopped",
  "external_id": "sub_1Q2w3E4r5T6y",
  "months_total": 3,
  "months_used": 2,
  "term_starts_at": "2026-10-06T00:00:00Z",
  "term_ends_at": "2027-01-06T00:00:00Z",
  "stopped_at": "2026-11-20T12:00:00Z",
  "stop_reason": "partner_cancelled"
}

• external_id is your subscription id, as your handoff sent it. Every supply the subscription bought carries the same one, so it is how you find the plan on your side.
• status is active while months remain, exhausted once every month is used, and stopped once the plan has ended.
• stop_reason says who ended it: partner_cancelled (your subscription was cancelled), check_in_declined (a clinician declined a monthly check-in after the first month) or staff_stopped (the clinic stopped it). It is null until the plan stops.

A test credential is answered 404: the sandbox holds no supplies.

When a plan stops

A stop ends every supply of the subscription at once and announces it with one supply.stopped.v1 event about the newest of them. A repeated stop changes nothing and announces nothing. Orders a clinician had already approved still ship; check-ins still waiting for a clinician are withdrawn, and each withdrawn case raises its own case.cancelled.v1. See Events and realtime.