Reorder exposes a full set of customer-facing subscription management endpoints under /store/customers/me/subscriptions. You can use these to build a self-service portal where customers can view their active subscriptions, change delivery frequency, update their address, skip a delivery, swap to a different product, retry a failed payment, pause or resume billing, and request cancellation — all without leaving your storefront.
Authentication
All customer subscription endpoints require an authenticated customer session. Include the customer’s session cookie or a bearer token with each request:
Authorization: Bearer <customer_token>
401. Requests for subscriptions that belong to a different customer return 403.
Listing subscriptions
Retrieve all subscriptions for the authenticated customer:
GET /store/customers/me/subscriptions
{
"subscriptions": [
{
"id": "sub_123",
"reference": "SUB-001",
"status": "active",
"product_title": "Daily Vitamins",
"variant_title": "60 capsules",
"next_renewal_at": "2026-05-01T10:00:00.000Z",
"active_cancellation_case": null
}
]
}
Viewing subscription detail
Retrieve the full detail for a single subscription:
GET /store/customers/me/subscriptions/:id
| Field | Description |
|---|
frequency_interval | Billing cadence unit: "week", "month", or "year" |
frequency_value | Number of intervals between billings |
effective_next_renewal_at | Projected next delivery date, accounting for skipped cycles |
last_renewal_at | When the most recent renewal ran |
shipping_address | The address snapshot for this subscription’s deliveries |
payment_status | Current payment status |
payment_provider_id | The payment provider handling this subscription |
payment_recovery | Active dunning recovery case, if any |
scheduled_plan_change | Pending variant or cadence update, if one is queued |
active_cancellation_case | Active cancellation case, if one is open |
Managing subscriptions
All management actions return a refreshed subscription detail payload so your UI can update in place without a separate fetch.
Pause
Pause billing on a subscription. Optionally provide a reason and an effective date:
POST /store/customers/me/subscriptions/:id/pause
{
"reason": "Taking a short break",
"effective_at": "2026-04-15T10:00:00.000Z"
}
Resume
Resume a paused subscription. Optionally preserve the original billing anchor date:
POST /store/customers/me/subscriptions/:id/resume
{
"resume_at": "2026-04-20T10:00:00.000Z",
"preserve_billing_anchor": true
}
Change frequency
Schedule a cadence change for the next renewal. The current variant stays unchanged. The new cadence must be valid according to the active plan for this subscription:
POST /store/customers/me/subscriptions/:id/change-frequency
{
"frequency_interval": "month",
"frequency_value": 2,
"effective_at": "2026-05-01T10:00:00.000Z"
}
Change address
Update the shipping address used for future deliveries:
POST /store/customers/me/subscriptions/:id/change-address
{
"first_name": "Jane",
"last_name": "Doe",
"address_1": "Main Street 1",
"city": "Copenhagen",
"postal_code": "2100",
"country_code": "dk"
}
Skip next delivery
Mark the next renewal cycle as skipped. The subscription resumes automatically at the following cycle. This endpoint takes no request body:
POST /store/customers/me/subscriptions/:id/skip-next-delivery
Swap product
Schedule a product or variant swap. The target variant must belong to the same product and be allowed by the active plan. The change applies at the next eligible renewal:
POST /store/customers/me/subscriptions/:id/swap-product
{
"variant_id": "variant_123",
"frequency_interval": "month",
"frequency_value": 1,
"effective_at": "2026-05-01T10:00:00.000Z"
}
Retry payment
Trigger a manual payment retry for a subscription that is in a recoverable failed-payment state. Include an optional reason to log with the retry attempt:
POST /store/customers/me/subscriptions/:id/retry-payment
{
"reason": "Customer requested immediate retry"
}
This endpoint returns 409 if the subscription does not have a retry-eligible payment recovery case. Check payment_recovery in the subscription detail before surfacing this action to the customer.
Request cancellation
Start a cancellation case for the subscription. Provide a reason category and an optional free-text reason:
POST /store/customers/me/subscriptions/:id/cancellation
{
"reason": "Too expensive right now",
"reason_category": "price",
"notes": "Customer started cancellation from storefront"
}
id, status, subscription_id, and the submitted reason fields. The subscription is not immediately cancelled — the case enters the configured cancellation and retention workflow.
Surfacing actions based on subscription status
Not all actions are relevant for every subscription state. Use the subscription’s status field to show the appropriate actions in your portal:
| Status | Available actions |
|---|
active | Pause, change frequency, change address, skip next delivery, swap product, cancel |
paused | Resume, change address, cancel |
past_due | Retry payment, change address, cancel |
cancelled | None |