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

# Subscription Checkout

> Use the subscribe endpoint to convert a prepared cart into a subscription at checkout, with frequency and offer data attached as line item metadata.

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.

```bash theme={null}
POST /store/carts/:id/subscribe
```

The endpoint returns the newly created subscription along with the completed order.

On the first successful creation, Reorder also records a `subscription.created` activity-log event for that subscription. In Admin, operators will see the storefront customer as the actor for that first event.

## Required line item metadata

Each subscription line item must include the following metadata fields:

| Field                | Type                          | Description                                |
| -------------------- | ----------------------------- | ------------------------------------------ |
| `is_subscription`    | `boolean`                     | Marks the line item as a subscription item |
| `frequency_interval` | `"week" \| "month" \| "year"` | The time unit for billing cadence          |
| `frequency_value`    | positive integer              | The 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:

| Field                         | Value            | Description                                      |
| ----------------------------- | ---------------- | ------------------------------------------------ |
| `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:

```typescript theme={null}
// 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.

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

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