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

# Subscriptions

> A subscription links a customer to a product variant on a recurring schedule. Learn about statuses, lifecycle transitions, and key fields.

A subscription in Reorder connects a customer to a specific product variant and bills them on a recurring schedule — for example, every month or every two weeks. When a customer completes a subscription checkout, Reorder creates a subscription record, sets the first renewal date, and schedules the first renewal cycle automatically. From that point on, the Admin dashboard and the Store API give you full visibility and control over the subscription's lifecycle.

## What a subscription tracks

Each subscription holds everything Reorder needs to manage the recurring relationship:

| Field                       | Description                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `reference`                 | Human-readable identifier shown in the Admin (for example, `SUB-001`)                                                          |
| `status`                    | Current lifecycle state: `active`, `paused`, `past_due`, or `cancelled`                                                        |
| `frequency_interval`        | The time unit for billing cadence: `week`, `month`, or `year`                                                                  |
| `frequency_value`           | The number of intervals between billings (for example, `2` with `month` means every 2 months)                                  |
| `next_renewal_at`           | The billing anchor date used by the renewal scheduler                                                                          |
| `effective_next_renewal_at` | The projected next delivery date shown in Admin and storefront — differs from `next_renewal_at` when the next cycle is skipped |
| `skip_next_cycle`           | When `true`, the upcoming renewal is skipped and rescheduled for the following cycle                                           |
| `pending_update_data`       | A scheduled plan or cadence change that will be applied at the next eligible renewal                                           |
| `started_at`                | When the subscription became active                                                                                            |
| `last_renewal_at`           | When the most recent successful renewal ran                                                                                    |

## Subscription statuses

| Status      | What it means                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `active`    | The subscription is billing normally. Renewals run on schedule.                                                                           |
| `paused`    | Billing is temporarily stopped. No renewals run while paused. The subscription resumes when you or the customer triggers a resume action. |
| `past_due`  | A renewal payment failed and dunning is active. The subscription stays in this state until the payment recovers or the case is closed.    |
| `cancelled` | The subscription has ended. No further renewals will run.                                                                                 |

<Note>
  A subscription moves to `past_due` automatically when a renewal payment fails and qualifies for dunning. It returns to `active` when the payment is successfully recovered.
</Note>

## Lifecycle transitions

Subscriptions move between statuses through explicit actions, not automatically (except for the `past_due` transition, which happens during renewal execution):

| From       | To          | Trigger                                      |
| ---------- | ----------- | -------------------------------------------- |
| `active`   | `paused`    | Pause action (Admin or Store API)            |
| `active`   | `past_due`  | Renewal payment failure starts dunning       |
| `active`   | `cancelled` | Cancel action or finalized cancellation case |
| `paused`   | `active`    | Resume action (Admin or Store API)           |
| `paused`   | `cancelled` | Cancel action or finalized cancellation case |
| `past_due` | `active`    | Dunning recovery succeeds                    |
| `past_due` | `cancelled` | Cancel action or finalized cancellation case |

## How subscriptions are created

Subscriptions are created through the checkout flow. When a cart line item carries subscription metadata (frequency interval and frequency value), Reorder synchronizes subscription pricing on the cart and then completes the subscription purchase through `POST /store/carts/:id/subscribe` instead of the standard Medusa cart complete route. Reorder validates the subscription metadata, completes the cart into a standard Medusa order, creates the subscription record, schedules the first renewal cycle, and writes an initial `subscription.created` event to the Activity Log with the customer recorded as the actor.

The checkout pricing adjustment is applied as a manual line-item adjustment identified by `provider_id = "subscription_discount"`. This keeps the subscription discount separate from Medusa promotion-code semantics while still allowing the discounted total to flow into payment and order creation.

<Warning>
  A cart must contain only subscription line items when using the subscribe endpoint. Mixed carts — combining subscription and one-time items — are not supported.
</Warning>

## Pending plan changes

You can schedule a plan change on an active subscription using the schedule-plan-change action. The change is stored in `pending_update_data` and applied during the next eligible renewal cycle rather than immediately. The pending change includes the target variant, frequency, and an optional effective date.

The Admin detail view shows a preview of the pending change alongside the current plan so you can review it before it takes effect.

## Admin and Store API actions

Reorder exposes subscription management through both the Admin API and the Store API.

**Admin API** (`/admin/subscriptions`):

* List and search subscriptions
* View full subscription detail
* Pause, resume, and cancel
* Schedule a plan change
* Update the shipping address

**Store API** (`/store/customers/me/subscriptions`):

* List and view the authenticated customer's subscriptions
* Pause, resume, and change frequency
* Change shipping address
* Skip the next delivery
* Swap to a different product variant
* Retry a failed payment
* Initiate a cancellation request