flintDocs

Subscription offers

The Subscription offer object#

Every field on a subscription offer, as returned by retrieve and carried by the endpoints below.

Attributes

billing_interval_optionsarray of objectRequired
created_atstringRequired

RFC3339 timestamp.

metadatamap of stringRequired
namestringRequired
product_idsarray of stringRequired

Catalog targets for new signups. At least one product or variant is required.

promotion_idstring or nullRequired

An active promotion with forever recurrence. On PATCH, null removes the discount for new signups; omission keeps it.

statusenumRequired
  • active
  • inactive
  • archived
subscription_delivery_method_idsarray of stringRequired

Delivery methods offered at signup. An empty array uses the store's checkout defaults. Existing subscriptions keep their selected method.

subscription_offer_idstringRequired
updated_atstringRequired

RFC3339 timestamp.

variant_idsarray of stringRequired

Catalog targets for new signups. At least one product or variant is required.

versionintegerRequired

List subscription offers#

GET/v1/subscription-offers

Requires scope commerce.subscription_plans.read or commerce.subscription_plans.write

List subscription offers. Offer changes affect new signups only. Existing subscriptions keep their terms.

Query parameters

page_sizeinteger
page_tokenstring
statusenum
  • active
  • inactive
  • archived
product_idstring
variant_idstring
querystring
sort_byenum
  • created_at
  • updated_at
  • name
sort_directionenum
  • asc
  • desc

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/subscription-offers \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create subscription offer#

POST/v1/subscription-offersIdempotent

Requires scope commerce.subscription_plans.write

Create subscription offer. Offer changes affect new signups only. Existing subscriptions keep their terms.

Request body

billing_interval_optionsarray of objectRequired
metadatamap of string
namestringRequired
product_idsarray of string

Catalog targets for new signups. At least one product or variant is required.

promotion_idstring or null

An active promotion with forever recurrence. On PATCH, null removes the discount for new signups; omission keeps it.

statusenum
  • active
  • inactive
subscription_delivery_method_idsarray of string

Delivery methods offered at signup. An empty array uses the store's checkout defaults. Existing subscriptions keep their selected method.

variant_idsarray of string

Catalog targets for new signups. At least one product or variant is required.

Response · 201

dataobjectRequired

Recurring terms offered on catalog products or variants. Updates affect new signups; existing subscriptions keep their paid signup terms.

metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/subscription-offers \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "billing_interval_options": [
      {
        "billing_interval": "daily",
        "billing_interval_count": 0
      }
    ],
    "name": ""
  }'

Get subscription offer#

GET/v1/subscription-offers/{subscription_offer_id}

Requires scope commerce.subscription_plans.read or commerce.subscription_plans.write

Get subscription offer. Offer changes affect new signups only. Existing subscriptions keep their terms.

Path parameters

subscription_offer_idstringRequired

Subscription offer ID.

Response · 200

Same response as Create subscription offer.

curl https://api.withflintpay.com/v1/subscription-offers/{subscription_offer_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update subscription offer#

PATCH/v1/subscription-offers/{subscription_offer_id}Idempotent

Requires scope commerce.subscription_plans.write

Update subscription offer. Offer changes affect new signups only. Existing subscriptions keep their terms.

Path parameters

subscription_offer_idstringRequired

Subscription offer ID.

Request body

billing_interval_optionsarray of object
expected_versioninteger

The version read before editing. A mismatch returns SUBSCRIPTION_OFFER_VERSION_CONFLICT.

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring
product_idsarray of string

Catalog targets for new signups. At least one product or variant is required.

promotion_idstring or null

An active promotion with forever recurrence. On PATCH, null removes the discount for new signups; omission keeps it.

statusenum
  • active
  • inactive
subscription_delivery_method_idsarray of string

Delivery methods offered at signup. An empty array uses the store's checkout defaults. Existing subscriptions keep their selected method.

variant_idsarray of string

Catalog targets for new signups. At least one product or variant is required.

Response · 200

Same response as Create subscription offer.

curl -X PATCH https://api.withflintpay.com/v1/subscription-offers/{subscription_offer_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "billing_interval_options": [
      {
        "billing_interval": "daily",
        "billing_interval_count": 0
      }
    ],
    "expected_version": 0,
    "metadata": {},
    "name": "",
    "product_ids": [
      ""
    ],
    "promotion_id": "",
    "status": "active",
    "subscription_delivery_method_ids": [
      ""
    ],
    "variant_ids": [
      ""
    ]
  }'

Archive subscription offer#

DELETE/v1/subscription-offers/{subscription_offer_id}Idempotent

Requires scope commerce.subscription_plans.write

Archive subscription offer. Offer changes affect new signups only. Existing subscriptions keep their terms.

Path parameters

subscription_offer_idstringRequired

Subscription offer ID.

Query parameters

expected_versioninteger

Response · 200

Same response as Create subscription offer.

curl -X DELETE https://api.withflintpay.com/v1/subscription-offers/{subscription_offer_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?