API References
Endpoint-level reference for the Joy Subscription Storefront REST API (v1). Every path on these pages is relative to the base URL and requires the two-layer authentication described in Authentication.
If you have not called the API before, read the Storefront API overview first — it explains the endpoint groups, the customer-scoped security model, and the error format shared by every endpoint below.
Reference pages
| Page | What it covers |
|---|---|
| Subscriptions (Read) | List a customer's subscription contracts, fetch full contract detail, preview upcoming and historical orders, preview the next charge, and resolve available shipping options. All read-only. |
| Subscription Management | Mutate a contract: pause, resume, cancel, swap product, change frequency, update shipping address, payment method and shipping option, manage contract and upcoming-order lines, act on billing cycles, and apply discounts. |
| Trial | Read the trial status of a single contract. Read-only, carries no PII. |
| Data Types & Enums | The shared types and enumerations returned by every endpoint. Integrate against these machine-readable values rather than display strings. |
Before you integrate
- Authenticate with both identities. An app credential pair (machine identity) and a customer-account session (end-user identity) are required together on every call.
- Expect customer scoping. A request can only ever read or modify contracts owned by the authenticated customer; anything else returns an error rather than another customer's data.
- Read the data types once. Data Types & Enums defines the status values, timestamp format (ISO 8601) and nullable fields used across all groups, so you only have to learn them one time.