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

> Convert a prepared cart into a subscription order using line item metadata as the source of truth for billing cadence.

Converts a cart to a subscription order at checkout. The cart must contain exactly one subscription line item with quantity `1`. Line item metadata is the authoritative source for subscription configuration.

Mixed carts (subscription and one-time items together) are not supported in the current version. Standard one-time checkout is not affected by this route.

<Info>This endpoint is idempotent — if the completed order is already linked to a subscription, the existing subscription is returned instead of creating a duplicate.</Info>

***

## POST /store/carts/:id/subscribe

### Path parameters

<ParamField path="id" type="string" required>
  Cart ID.
</ParamField>

### Line item metadata contract

The following metadata fields must be set on the subscription line item before calling this endpoint.

<ParamField body="line_item.metadata.is_subscription" type="boolean" required>
  Must be `true` to mark the line item as a subscription.
</ParamField>

<ParamField body="line_item.metadata.frequency_interval" type="string" required>
  Billing interval. One of `week`, `month`, or `year`.
</ParamField>

<ParamField body="line_item.metadata.frequency_value" type="number" required>
  Billing cadence as a positive integer.
</ParamField>

### Optional cart metadata

<ParamField body="cart.metadata.purchase_mode" type="string">
  When present, must be `"subscription"`. Mixed purchase mode is not supported.
</ParamField>

```json Line item metadata example theme={null}
{
  "metadata": {
    "is_subscription": true,
    "frequency_interval": "month",
    "frequency_value": 1
  }
}
```

### Response

Returns the created subscription on success. If the order is already linked to a subscription (idempotent re-call), returns the existing subscription.

When the subscription is created for the first time, Reorder also appends a `subscription.created` entry to the Activity Log. The event is recorded with the storefront customer as the actor so operators can see that the subscription originated from checkout.

### Errors

| Code  | Error          | Meaning                                                                                            |
| ----- | -------------- | -------------------------------------------------------------------------------------------------- |
| `400` | `invalid_data` | Mixed cart, missing subscription line item, invalid metadata, or unsupported `purchase_mode` value |