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. |
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.
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 store checkout flow. When a cart line item carries subscription metadata (frequency interval, frequency value, and offer configuration), you complete the cart by calling 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, and schedules the first renewal cycle.
A cart must contain only subscription line items when using the subscribe endpoint. Mixed carts — combining subscription and one-time items — are not supported.
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