Skip to main content
When a customer selects a subscription offer on your storefront and proceeds to checkout, you complete their cart through a dedicated endpoint instead of the standard Medusa cart-complete route. Reorder validates the subscription metadata on the cart’s line items, converts the cart into a standard Medusa order, creates the subscription record, and schedules the first renewal cycle — all in a single call.

​
How subscription checkout works

Call POST /store/carts/:id/subscribe in place of the standard cart-complete route when the cart contains a subscription item. Reorder reads the subscription configuration from line item metadata to determine the billing cadence and offer terms. 
POST /store/carts/:id/subscribe
The endpoint returns the newly created subscription along with the completed order.

​
Required line item metadata

Each subscription line item must include the following metadata fields:
FieldTypeDescription
is_subscriptionbooleanMarks the line item as a subscription item
frequency_interval"week" | "month" | "year"The time unit for billing cadence
frequency_valuepositive integerThe number of intervals between billings
These fields are the source of truth for the subscription’s cadence. Reorder reads them directly from the line item, regardless of any cart-level metadata.

​
Optional cart metadata

You can also set purchase_mode on the cart itself to make the intent explicit:
FieldValueDescription
cart.metadata.purchase_mode"subscription"Signals that the cart is a subscription checkout
If purchase_mode is present, it must be set to "subscription". Any other value returns a 400 error.

​
Setting metadata before checkout

Set line item and cart metadata when the customer confirms their subscription selection. The example below shows a typical pre-checkout call using the Medusa JS SDK: 
// Update the line item with subscription metadata
await medusa.store.cart.updateLineItem(cartId, lineItemId, {
  metadata: {
    is_subscription: true,
    frequency_interval: "month",
    frequency_value: 1,
  },
});

// Optionally mark the cart as a subscription checkout
await medusa.store.cart.update(cartId, {
  metadata: {
    purchase_mode: "subscription",
  },
});

// Complete checkout through the subscribe endpoint
const { subscription, order } = await medusa.client.fetch(
  `/store/carts/${cartId}/subscribe`,
  { method: "POST" }
);

​
Constraints

The subscribe endpoint enforces the following rules in the current release:
  • Exactly one subscription line item — the cart must contain a single subscription item. Multiple subscription line items are not supported.
  • Quantity of 1 — the subscription line item must have a quantity of 1.
  • No mixed carts — a cart cannot combine subscription and one-time-purchase items. Submit a separate cart for one-time items.
A cart that violates any of these constraints returns a 400 error.
Mixed carts are not supported. If a customer wants to purchase both a subscription item and a one-time item in the same session, use separate carts and complete them through their respective endpoints.

​
Idempotency after cart completion

The subscribe endpoint is safe to call more than once after the cart is already complete. If the order created from the cart is already linked to a subscription, Reorder returns the existing subscription instead of creating a duplicate. This means retries due to network issues or client-side double-submits will not produce extra subscriptions.