Subscriptions

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

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

Get Started

Core Concepts

Admin UI

Configuration

Storefront

What a subscription tracks

Subscription statuses

Lifecycle transitions

How subscriptions are created

Pending plan changes

Admin and Store API actions

​What a subscription tracks

​Subscription statuses

​Lifecycle transitions

​How subscriptions are created

​Pending plan changes

​Admin and Store API actions

What a subscription tracks

Subscription statuses

Lifecycle transitions

How subscriptions are created

Pending plan changes

Admin and Store API actions