> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reorderjs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Customer Subscriptions
> Let customers list and manage their own subscriptions — pause, resume, skip, swap, change frequency or address, retry payment, and request cancellation.
The customer subscription endpoints expose self-service subscription management on the storefront. An authenticated customer can view their subscriptions, make lifecycle changes, and initiate a cancellation. All routes require a valid customer session or bearer token, and all subscription mutations enforce ownership — the subscription must belong to the authenticated customer. Mutations return the refreshed subscription detail payload unless noted otherwise.
All routes use `authenticate("customer", ["session", "bearer"])`. Ownership is validated against the authenticated customer's `actor_id`.
***
## GET /store/customers/me/subscriptions
Returns the authenticated customer's subscriptions with storefront summary data.
### Response
Subscription ID.
Human-readable reference (e.g. `SUB-001`).
Current subscription status.
Product name.
Variant name.
Next scheduled renewal date.
Active cancellation case summary, or `null`.
***
## GET /store/customers/me/subscriptions/:id
Returns the full storefront-safe detail payload for one subscription.
### Path parameters
Subscription ID. Must belong to the authenticated customer.
### Response
Subscription ID.
Human-readable reference.
Current subscription status.
Product name.
Variant name.
Billing interval: `week`, `month`, or `year`.
Billing cadence as a positive integer.
Technical billing anchor date.
Projected next renewal accounting for any skip.
Last successful renewal timestamp.
Current shipping address snapshot.
Current payment status.
Payment provider identifier.
Active dunning recovery case, or `null`.
Pending variant or cadence change, or `null`.
Active cancellation case summary, or `null`.
***
## POST /store/customers/me/subscriptions/:id/pause
Pauses the customer's subscription.
### Path parameters
Subscription ID.
### Body parameters
Optional reason for the pause.
ISO datetime for when the pause takes effect. Optional.
```json Request example theme={null}
{
"reason": "Taking a short break",
"effective_at": "2026-04-15T10:00:00.000Z"
}
```
***
## POST /store/customers/me/subscriptions/:id/resume
Resumes a paused subscription.
### Path parameters
Subscription ID.
### Body parameters
ISO datetime for when the subscription resumes. Optional.
When `true`, keeps the original billing anchor date. Optional.
```json Request example theme={null}
{
"resume_at": "2026-04-20T10:00:00.000Z",
"preserve_billing_anchor": true
}
```
***
## POST /store/customers/me/subscriptions/:id/change-frequency
Schedules a cadence change for the subscription. The current variant stays unchanged. The new cadence is validated against active Plans & Offers.
### Path parameters
Subscription ID.
### Body parameters
New billing interval. One of `week`, `month`, or `year`.
New billing cadence as a positive integer.
ISO datetime when the change becomes effective. Optional.
```json Request example theme={null}
{
"frequency_interval": "month",
"frequency_value": 2,
"effective_at": "2026-05-01T10:00:00.000Z"
}
```
***
## POST /store/customers/me/subscriptions/:id/change-address
Updates the subscription shipping address.
### Path parameters
Subscription ID.
### Body parameters
First name.
Last name.
Primary address line.
City.
Postal or ZIP code.
Two-letter ISO country code.
```json Request example theme={null}
{
"first_name": "Jane",
"last_name": "Doe",
"address_1": "Main Street 1",
"city": "Copenhagen",
"postal_code": "2100",
"country_code": "dk"
}
```
***
## POST /store/customers/me/subscriptions/:id/skip-next-delivery
Marks the next renewal cycle as skipped. No request body is required.
### Path parameters
Subscription ID.
***
## POST /store/customers/me/subscriptions/:id/swap-product
Schedules a product or variant swap. The target variant must belong to the subscription product and be allowed by active Plans & Offers.
### Path parameters
Subscription ID.
### Body parameters
Target variant ID.
Billing interval for the new variant. One of `week`, `month`, or `year`.
Billing cadence as a positive integer.
ISO datetime when the swap becomes effective. Optional.
```json Request example theme={null}
{
"variant_id": "variant_123",
"frequency_interval": "month",
"frequency_value": 1,
"effective_at": "2026-05-01T10:00:00.000Z"
}
```
***
## POST /store/customers/me/subscriptions/:id/retry-payment
Runs a manual payment retry for a retry-eligible dunning recovery case.
### Path parameters
Subscription ID.
### Body parameters
Optional reason for the manual retry.
```json Request example theme={null}
{
"reason": "Customer requested immediate retry"
}
```
### Errors
| Code | Error | Meaning |
| ----- | ---------- | ---------------------------------------------- |
| `409` | `conflict` | No retry-eligible payment recovery case exists |
***
## POST /store/customers/me/subscriptions/:id/cancellation
Starts a cancellation case for the subscription. Returns a minimal cancellation case payload rather than the full subscription detail.
### Path parameters
Subscription ID. Must belong to the authenticated customer.
### Body parameters
Free-text churn reason.
Normalized reason category. One of `price`, `product_fit`, `delivery`, `billing`, `temporary_pause`, `switched_competitor`, or `other`.
Optional notes from the customer.
```json Request example theme={null}
{
"reason": "Too expensive right now",
"reason_category": "price",
"notes": "Customer started cancellation from storefront"
}
```
### Response
Cancellation case ID.
Initial case status.
Linked subscription ID.
Submitted churn reason.
Submitted reason category.