> ## 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 Portal

> Use the Store API's customer subscription endpoints to let authenticated customers view, manage, and cancel their subscriptions from your storefront.

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:

```bash theme={null}
Authorization: Bearer <customer_token>
```

Requests without valid authentication return `401`. Requests for subscriptions that belong to a different customer return `403`.

## Listing subscriptions

Retrieve all subscriptions for the authenticated customer:

```bash theme={null}
GET /store/customers/me/subscriptions
```

```json theme={null}
{
  "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:

```bash theme={null}
GET /store/customers/me/subscriptions/:id
```

The detail payload includes all fields from the list view, plus:

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

```bash theme={null}
POST /store/customers/me/subscriptions/:id/pause
```

```json theme={null}
{
  "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:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/resume
```

```json theme={null}
{
  "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:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/change-frequency
```

```json theme={null}
{
  "frequency_interval": "month",
  "frequency_value": 2,
  "effective_at": "2026-05-01T10:00:00.000Z"
}
```

### Change address

Update the shipping address used for future deliveries:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/change-address
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/swap-product
```

```json theme={null}
{
  "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:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/retry-payment
```

```json theme={null}
{
  "reason": "Customer requested immediate retry"
}
```

<Warning>
  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.
</Warning>

### Request cancellation

Start a cancellation case for the subscription. Provide a reason category and an optional free-text reason:

```bash theme={null}
POST /store/customers/me/subscriptions/:id/cancellation
```

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

The response returns a minimal cancellation case payload with `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                                                                              |