Skip to main content
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

​
subscriptions
object[]
required

​
GET /store/customers/me/subscriptions/:id

Returns the full storefront-safe detail payload for one subscription.

​
Path parameters

​
id
string
required
Subscription ID. Must belong to the authenticated customer.

​
Response

​
subscription
object
required

​
POST /store/customers/me/subscriptions/:id/pause

Pauses the customer’s subscription.

​
Path parameters

​
id
string
required
Subscription ID.

​
Body parameters

​
reason
string
Optional reason for the pause.
​
effective_at
string
ISO datetime for when the pause takes effect. Optional.
Request example
{
  "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

​
id
string
required
Subscription ID.

​
Body parameters

​
resume_at
string
ISO datetime for when the subscription resumes. Optional.
​
preserve_billing_anchor
boolean
When true, keeps the original billing anchor date. Optional.
Request example
{
  "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

​
id
string
required
Subscription ID.

​
Body parameters

​
frequency_interval
string
required
New billing interval. One of week, month, or year.
​
frequency_value
number
required
New billing cadence as a positive integer.
​
effective_at
string
ISO datetime when the change becomes effective. Optional.
Request example
{
  "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

​
id
string
required
Subscription ID.

​
Body parameters

​
first_name
string
required
First name.
​
last_name
string
required
Last name.
​
address_1
string
required
Primary address line.
​
city
string
required
City.
​
postal_code
string
required
Postal or ZIP code.
​
country_code
string
required
Two-letter ISO country code.
Request example
{
  "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

​
id
string
required
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

​
id
string
required
Subscription ID.

​
Body parameters

​
variant_id
string
required
Target variant ID.
​
frequency_interval
string
required
Billing interval for the new variant. One of week, month, or year.
​
frequency_value
number
required
Billing cadence as a positive integer.
​
effective_at
string
ISO datetime when the swap becomes effective. Optional.
Request example
{
  "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

​
id
string
required
Subscription ID.

​
Body parameters

​
reason
string
Optional reason for the manual retry.
Request example
{
  "reason": "Customer requested immediate retry"
}

​
Errors

CodeErrorMeaning
409conflictNo 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

​
id
string
required
Subscription ID. Must belong to the authenticated customer.

​
Body parameters

​
reason
string
Free-text churn reason.
​
reason_category
string
Normalized reason category. One of price, product_fit, delivery, billing, temporary_pause, switched_competitor, or other.
​
notes
string
Optional notes from the customer.
Request example
{
  "reason": "Too expensive right now",
  "reason_category": "price",
  "notes": "Customer started cancellation from storefront"
}

​
Response

​
cancellation_case
object
required