Patient Shop Subscriptions

Use GET /shop to read the same storefront configuration shown in VitaRelay. Every product, custom item, and package returns:

Field	Meaning
`item_kind`	`product`, `custom`, or `bundle`
`purchase_mode`	`one_time`, `subscription`, or `both`
`available_cadences`	`["weekly","monthly","quarterly"]` when subscribable, otherwise `[]`
`default_cadence`	Cadence used when you omit one
`first_order_immediate`	Bill and ship the first cycle right away
`requires_shipping`	`false` for services (and service-only packages)
`requires_prescription`	Whether checkout requires a valid prescription
`patient_price_cents`	What the patient pays

Cost and pharmacy fields are never returned.

Create

Create subscriptions with POST /subscriptions and the subscriptions:write scope. Send the patient, item kind, storefront item id, quantity, cadence, saved payment method, and a saved address for shippable items.

{
  "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "item_kind": "product",
  "item_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
  "quantity": 1,
  "cadence": "monthly",
  "payment_method_id": "9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
  "ship_to_address_id": "8d7e6f5a-4b3c-2d1e-0f9a-8b7c6d5e4f3a"
}

Services are charged each cycle without shipping or pharmacy dispatch. Rx validation applies only when the storefront item already requires a prescription. Prices are always resolved server-side from the live clinic storefront.

Buy through POST /orders

Each order line may carry purchase (one_time default, or subscription), cadence, and quantity. Lines use either product_id (catalog product, unchanged behaviour) or item_kind + item_id. Subscription lines require a top-level payment_method_id (patient saved card) and use ship_to_address_id or the patient’s preferred address.

{
  "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "payment_method_id": "9e8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b",
  "items": [
    { "product_id": "aad522c1-a9fc-41c5-962e-a015f9cd4c95", "quantity": 1, "purchase": "subscription", "cadence": "monthly" },
    { "item_kind": "custom", "item_id": "5e4f3a2b-1c0d-4a7b-8c6d-9e8f7a6b5c4d", "quantity": 1, "purchase": "subscription" }
  ]
}

Response: { "data": { "id": null, "order_id": null, "status": "subscribed", "subscription_ids": ["…", "…"] } }. When one-time lines are included, order_id is the order created for them and subscription_ids is returned alongside it.

Error (422)	When
`purchase_mode_not_allowed`	One-time purchase of a subscription-only item, or subscription to a one-time-only item
`invalid_cadence`	Cadence not weekly/monthly/quarterly, or none given and the item has no default
`payment_method_required`	Subscription line without a patient saved card you own
`shipping_required`	Shippable subscription item and the patient has no saved address (services never require one)
`unsupported_line`	One-time custom items and packages; patients buy those in the storefront

Endpoint examples

GET /subscriptions?patient_id=…&status=active → 200

{ "data": [{ "id": "0f1f2c9e-…", "item_kind": "product", "quantity": 1, "cadence": "monthly", "status": "active", "next_charge_at": "2026-10-25T04:06:14Z" }], "next_cursor": null }

POST /subscriptions → 201 When the item bills its first cycle at signup (first_order_immediate), the first charge is made during this call, using the patient’s saved card. Otherwise it is scheduled for next_charge_at. First charge succeeded:

{ "data": { "subscription_id": "0f1f2c9e-…", "status": "active", "next_charge_at": "2026-11-25T04:06:14Z",
  "order_id": "5a1c…", "order_number": "VR-10482",
  "first_charge": { "status": "charged", "charged_cents": 4900, "decline_reason": null } } }

Card declined (the subscription is still created and the charge is retried on the normal schedule):

{ "data": { "subscription_id": "0f1f2c9e-…", "status": "active", "next_charge_at": "2026-11-27T04:06:14Z",
  "order_id": "5a1c…", "order_number": "VR-10482",
  "first_charge": { "status": "declined", "charged_cents": 0, "decline_reason": "This transaction has been declined." } } }

first_charge.status is one of charged, declined (card refused), failed (the order could not be created; nothing was charged), not_charged (billing is switched off for the account), or scheduled (not due yet; no order is returned). decline_reason is a short, patient-safe message from the card network, or null. GET /subscriptions/{id} → 200

{ "subscription": { "id": "0f1f2c9e-…", "item_kind": "product", "quantity": 1, "cadence": "monthly", "status": "active", "paused_reason": null, "price_cents_snapshot": 6500, "next_charge_at": "2026-10-25T04:06:14Z", "card_brand": "Visa", "card_last4": "4242" }, "recent_cycles": [] }

PATCH /subscriptions/{id} with { "cadence": "quarterly" } → 200, same shape as GET. POST /subscriptions/{id}/pause, /resume, /cancel → 200 { "ok": true } POST /subscriptions/{id}/skip-next → 200 { "ok": true, "next_charge_at": "2026-11-25T04:06:14Z" }

Manage

Use GET /subscriptions, GET /subscriptions/{id}, PATCH /subscriptions/{id}, and the pause, resume, cancel, and skip-next actions. Cross-organization resources return 404. Organizations operating under another white-label brand cannot mutate storefronts or subscriptions. Those writes return 403 with white_label_restricted.

Events

Every subscription event’s data contains subscription_id, patient_id, item_kind, item_id, quantity, cadence, status, paused_reason, and next_charge_at. subscription.payment_failed fires on every failed attempt with attempt, max_attempts (3), next_retry_at, and final; the third failure also emits subscription.paused with reason: "payment_failed". Subscribe to subscription.created, subscription.updated, subscription.paused, subscription.resumed, subscription.canceled, subscription.renewed, subscription.payment_failed, and subscription.rx_hold. Dry-run billing does not emit renewal or payment events.

Saving a card for auto-renew (embedded checkout)

When paying an order with POST /v1/orders/{id}/pay, add "save_card": true alongside opaque_data. If the charge is approved, VitaRelay saves the card to the patient’s wallet (it becomes their default card if they don’t have one), and future subscription renewals charge it automatically. The response includes saved_payment_method_id (null if nothing was saved, including sandbox/dry-run orders). Only send save_card after the patient has agreed to have their card kept on file.

Getting Started

API Reference

Webhooks

Guides

Patient Shop Subscriptions

Patient Shop Subscriptions

Create

Buy through POST /orders

Endpoint examples

Manage

Events

Saving a card for auto-renew (embedded checkout)

​Patient Shop Subscriptions

​Create

​Buy through POST /orders

​Endpoint examples

​Manage

​Events

​Saving a card for auto-renew (embedded checkout)

Patient Shop Subscriptions

Create

Buy through POST /orders

Endpoint examples

Manage

Events

Saving a card for auto-renew (embedded checkout)