Store API: subscription offer endpoint

Resolve subscription offer data for a product or variant on the PDP, and convert a cart to a subscription at checkout with the subscribe endpoint.

The store offer endpoints handle subscription discovery and checkout on the storefront. The offer endpoint resolves which subscription cadences and discounts are available for a given product or variant — used to power PDP subscription selectors and pricing displays. The subscribe endpoint converts a cart to a subscription order, using line item metadata as the source of truth for the subscription configuration. Both routes are publicly accessible for read operations; the subscribe endpoint completes as part of normal cart checkout.

The subscribe endpoint at POST /store/carts/:id/subscribe is idempotent — if the completed order is already linked to a subscription, the existing subscription is returned.

---

GET /store/products/:id/subscription-offer

Returns the effective subscription offer for a product, optionally scoped to a specific variant. Variant-level offers take precedence over product-level offers. Returns is_subscription_available: false when no active offer exists.

Path parameters

id · string · required

Product ID.

Query parameters

variant_id · string

Optional variant ID. When provided, the response reflects the variant-level offer if one exists.

Response

subscription_offer · object · required

Show offer fields

is_subscription_available · boolean

Whether a subscription offer is available for this product or variant.

product_id · string

Resolved product ID.

variant_id · string | null

Resolved variant ID, or null when the offer applies at product level.

source_offer_id · string

ID of the Plans & Offers record that sourced this offer.

source_scope · string

Scope of the source offer: product or variant.

allowed_frequencies · object[]

Cadences the customer can choose. Each item contains frequency_interval, frequency_value, label, and a discount object with type and value.

discount_semantics · object | null

Global discount presentation rules for the offer, or null.

minimum_cycles · number | null

Minimum number of billing cycles required, or null.

trial · object | null

Trial configuration with duration and terms, or null when no trial applies.

Response example — offer available

{
  "subscription_offer": {
    "is_subscription_available": true,
    "product_id": "prod_123",
    "variant_id": "variant_123",
    "source_offer_id": "offer_456",
    "source_scope": "variant",
    "allowed_frequencies": [
      {
        "frequency_interval": "month",
        "frequency_value": 1,
        "label": "Every month",
        "discount": {
          "type": "percentage",
          "value": 10
        }
      },
      {
        "frequency_interval": "month",
        "frequency_value": 2,
        "label": "Every 2 months",
        "discount": {
          "type": "percentage",
          "value": 5
        }
      }
    ],
    "discount_semantics": null,
    "minimum_cycles": null,
    "trial": null
  }
}

Response example — no offer

{
  "subscription_offer": {
    "is_subscription_available": false,
    "product_id": "prod_789",
    "variant_id": null,
    "source_offer_id": null,
    "source_scope": null,
    "allowed_frequencies": [],
    "discount_semantics": null,
    "minimum_cycles": null,
    "trial": null
  }
}

---

POST /store/carts/:id/subscribe

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.

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

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