Skip to main content
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.
This endpoint is idempotent — if the completed order is already linked to a subscription, the existing subscription is returned instead of creating a duplicate.

​
POST /store/carts/:id/subscribe

​
Path parameters

​
id
string
required
Cart ID.

​
Line item metadata contract

The following metadata fields must be set on the subscription line item before calling this endpoint.
​
line_item.metadata.is_subscription
boolean
required
Must be true to mark the line item as a subscription.
​
line_item.metadata.frequency_interval
string
required
Billing interval. One of week, month, or year.
​
line_item.metadata.frequency_value
number
required
Billing cadence as a positive integer.

​
Optional cart metadata

​
cart.metadata.purchase_mode
string
When present, must be "subscription". Mixed purchase mode is not supported.
Line item metadata example
{
  "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.

​
Errors

CodeErrorMeaning
400invalid_dataMixed cart, missing subscription line item, invalid metadata, or unsupported purchase_mode value