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
object[]
required
GET /store/customers/me/subscriptions/:id
Returns the full storefront-safe detail payload for one subscription.Path parameters
string
required
Subscription ID. Must belong to the authenticated customer.
Response
object
required
POST /store/customers/me/subscriptions/:id/pause
Pauses the customer’s subscription.Path parameters
string
required
Subscription ID.
Body parameters
string
Optional reason for the pause.
string
ISO datetime for when the pause takes effect. Optional.
Request example
POST /store/customers/me/subscriptions/:id/resume
Resumes a paused subscription.Path parameters
string
required
Subscription ID.
Body parameters
string
ISO datetime for when the subscription resumes. Optional.
boolean
When
true, keeps the original billing anchor date. Optional.Request example
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
string
required
Subscription ID.
Body parameters
string
required
New billing interval. One of
week, month, or year.number
required
New billing cadence as a positive integer.
string
ISO datetime when the change becomes effective. Optional.
Request example
POST /store/customers/me/subscriptions/:id/change-address
Updates the subscription shipping address.Path parameters
string
required
Subscription ID.
Body parameters
string
required
First name.
string
required
Last name.
string
required
Primary address line.
string
required
City.
string
required
Postal or ZIP code.
string
required
Two-letter ISO country code.
Request example
POST /store/customers/me/subscriptions/:id/skip-next-delivery
Marks the next renewal cycle as skipped. No request body is required.Path parameters
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
string
required
Subscription ID.
Body parameters
string
required
Target variant ID.
string
required
Billing interval for the new variant. One of
week, month, or year.number
required
Billing cadence as a positive integer.
string
ISO datetime when the swap becomes effective. Optional.
Request example
POST /store/customers/me/subscriptions/:id/retry-payment
Runs a manual payment retry for a retry-eligible dunning recovery case.Path parameters
string
required
Subscription ID.
Body parameters
string
Optional reason for the manual retry.
Request example
Errors
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
string
required
Subscription ID. Must belong to the authenticated customer.
Body parameters
string
Free-text churn reason.
string
Normalized reason category. One of
price, product_fit, delivery, billing, temporary_pause, switched_competitor, or other.string
Optional notes from the customer.
Request example
Response
object
required