> ## 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, address, or payment method, 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, manage saved payment methods, 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.

> [!NOTE]
>
> 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*

**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*

**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\_method** `object | null`

Summary of the current saved payment method (brand, last4, expiry), or `null`.

**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.

```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

**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.

```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

**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.

```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

**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.

```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

**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.

```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

**id** `string` *required*

Subscription ID.

### Body parameters

**reason** `string`

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

**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.

```json Request example theme={null}
{
  "reason": "Too expensive right now",
  "reason_category": "price",
  "notes": "Customer started cancellation from storefront"
}
```

### Response

**cancellation\_case** `object` *required*

**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.

***

## GET /store/customers/me/subscriptions/:id/payment-methods

Lists the authenticated customer's saved payment methods for the subscription's payment provider.

### Path parameters

**id** `string` *required*

Subscription ID. Must belong to the authenticated customer.

### Response

**payment\_provider\_id** `string | null`

The payment provider ID associated with the subscription, or `null` if none is configured.

**payment\_methods** `object[]` *required*

**payment method fields**

**id** `string`

Payment method identifier.

**provider\_id** `string`

Payment provider identifier.

**type** `string`

Type of payment method (e.g. `card`).

**brand** `string | null`

Card brand (e.g. `visa`, `mastercard`).

**last4** `string | null`

Last 4 digits of the card number.

**exp\_month** `number | null`

Card expiration month.

**exp\_year** `number | null`

Card expiration year.

**created\_at** `number | null`

Unix timestamp of when the payment method was created.

**is\_current** `boolean`

Whether this is the payment method currently assigned to the subscription.

```json Response example theme={null}
{
  "payment_provider_id": "pp_stripe_stripe",
  "payment_methods": [
    {
      "id": "pm_123",
      "provider_id": "pp_stripe_stripe",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 4,
      "exp_year": 2030,
      "created_at": 1700000000,
      "is_current": true
    }
  ]
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `404` | `not_found` | Subscription does not exist or does not belong to the authenticated customer |

***

## POST /store/customers/me/subscriptions/:id/payment-method

Changes the payment method the subscription renews with.

### Path parameters

**id** `string` *required*

Subscription ID. Must belong to the authenticated customer.

### Body parameters

**payment\_method\_id** `string` *required*

Identifier of the saved payment method.

**provider\_id** `string`

Payment provider identifier. Optional if the subscription already has a configured provider.

```json Request example theme={null}
{
  "payment_method_id": "pm_123",
  "provider_id": "pp_stripe_stripe"
}
```

### Response

Returns the refreshed subscription detail payload, matching `GET /store/customers/me/subscriptions/:id`.

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload, unknown payment method, or payment method not owned by the customer |
| `404` | `not_found` | Subscription does not exist or does not belong to the authenticated customer |
| `409` | `conflict` | Subscription status does not allow updating the payment method |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.