Store API: customer subscription endpoints

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

subscriptions · object[] · required

Show subscription summary fields

id · string

Subscription ID.

reference · string

Human-readable reference (e.g. SUB-001).

status · string

Current subscription status.

product_title · string

Product name.

variant_title · string

Variant name.

next_renewal_at · string

Next scheduled renewal date.

active_cancellation_case · object | null

Active cancellation case summary, or null.

---

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

Show subscription detail fields

id · string

Subscription ID.

reference · string

Human-readable reference.

status · string

Current subscription status.

product_title · string

Product name.

variant_title · string

Variant name.

frequency_interval · string

Billing interval: week, month, or year.

frequency_value · number

Billing cadence as a positive integer.

next_renewal_at · string

Technical billing anchor date.

effective_next_renewal_at · string

Projected next renewal accounting for any skip.

last_renewal_at · string | null

Last successful renewal timestamp.

shipping_address · object

Current shipping address snapshot.

payment_status · string

Current payment status.

payment_provider_id · string

Payment provider identifier.

payment_recovery · object | null

Active dunning recovery case, or null.

scheduled_plan_change · object | null

Pending variant or cadence change, or null.

active_cancellation_case · object | null

Active cancellation case summary, or null.

---

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

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

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

Show cancellation case fields

id · string

Cancellation case ID.

status · string

Initial case status.

subscription_id · string

Linked subscription ID.

reason · string

Submitted churn reason.

reason_category · string

Submitted reason category.