Subscription plans

Subscription plans are reusable billing templates: they define what to charge, how often to bill, and any trial or contract terms. A plan's line items can reference your catalog (variants or bundles) or be defined ad hoc with a name and unit price, and the plan can add a setup fee, a trial period, a contract term, and an early termination fee. Every money field on a plan must use the plan's currency.

One plan can be sold through multiple channels: create subscriptions against it directly, or pass its plan_id to a checkout session or payment link for Flint-hosted signup. Plans are archived rather than deleted, so existing subscriptions keep billing against the plan they were created with.

Start with the Subscription billing guide. For selling plans through hosted links, see subscription signup links.

Endpoints

GET/v1/subscription-plans
POST/v1/subscription-plans
GET/v1/subscription-plans/{plan_id}
PATCH/v1/subscription-plans/{plan_id}
POST/v1/subscription-plans/{plan_id}/archive
POST/v1/subscription-plans/{plan_id}/line-items
PATCH/v1/subscription-plans/{plan_id}/line-items/{subscription_plan_line_item_id}
DELETE/v1/subscription-plans/{plan_id}/line-items/{subscription_plan_line_item_id}

List subscription plans #

GET/v1/subscription-plans

Returns a paginated list of subscription plans for the authenticated merchant.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by subscription plan status.

activearchived

querystring

Search across subscription plan name and description.

sort_byenum

Sort field.

namecreated_atupdated_at

sort_directionenum

Sort direction.

ascdesc

created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

Response · 200

dataarray of objectrequired

metaobject

next_page_tokenstring

request_idstring

Bash

curl https://api.withflintpay.com/v1/subscription-plans \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "plan_id": "plan_123",
      "name": "Monthly Membership",
      "billing_interval": "monthly",
      "billing_interval_count": 1,
      "line_items": [
        {
          "subscription_plan_line_item_id": "spli_123",
          "name": "Membership",
          "unit_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "quantity": 1
        }
      ],
      "status": "active",
      "metadata": {
        "segment": "gold"
      },
      "currency": "USD",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create subscription plan #

POST/v1/subscription-plansIdempotent

Creates a subscription plan for the authenticated merchant.

Request body

billing_intervalenumrequired

dailyweeklymonthlyyearly

billing_interval_countintegerrequired

contract_term_monthsinteger

currencystringrequired

ISO 4217 currency code.

descriptionstring

early_termination_fee_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

image_urlstring

line_itemsarray of one of

metadatamap of string

namestringrequired

setup_fee_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

trial_period_daysinteger

Response · 201

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/subscription-plans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD"
  }'

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get subscription plan #

GET/v1/subscription-plans/{plan_id}

Returns a single subscription plan by ID.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl https://api.withflintpay.com/v1/subscription-plans/plan_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update subscription plan #

PATCH/v1/subscription-plans/{plan_id}Idempotent

Applies a sparse update to mutable subscription plan fields. Line items are mutated through the subscription plan line-item endpoints.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

Request body

contract_term_monthsinteger

descriptionstring

early_termination_fee_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

image_urlstring

metadatamap of string

namestring

setup_fee_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

trial_period_daysinteger

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X PATCH https://api.withflintpay.com/v1/subscription-plans/plan_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "Updated recurring membership plan",
    "metadata": {
      "segment": "vip"
    }
  }'

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Archive subscription plan #

POST/v1/subscription-plans/{plan_id}/archiveIdempotent

Archives a subscription plan. Plans with active subscriptions cannot be archived.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/subscription-plans/plan_123/archive \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Add subscription plan line items #

POST/v1/subscription-plans/{plan_id}/line-itemsIdempotent

Adds one or more line items to a subscription plan. Each created line item receives a stable subscription_plan_line_item_id.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

Request body

line_itemsarray of one ofrequired

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/subscription-plans/plan_123/line-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "line_items": [
      {
        "name": "Setup coaching",
        "unit_price_money": {
          "amount": 10000,
          "currency": "USD"
        },
        "quantity": 1
      }
    ]
  }'

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update subscription plan line item #

PATCH/v1/subscription-plans/{plan_id}/line-items/{subscription_plan_line_item_id}Idempotent

Sparsely updates one addressable subscription plan line item by subscription_plan_line_item_id. Omitted fields are unchanged. When changing variant_id or bundle_id, include modifiers to make modifier intent explicit; send modifiers: [] to select no modifiers.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

subscription_plan_line_item_idstringrequired

Stable subscription plan line item ID.

Request body

bundle_idstring

descriptionstring

modifiersarray of object

namestring

quantityinteger

Whole-number quantity; fractional quantities are not supported.

taxobject

unit_price_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

variant_idstring

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X PATCH https://api.withflintpay.com/v1/subscription-plans/plan_123/line-items/spli_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "quantity": 2
  }'

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Remove subscription plan line item #

DELETE/v1/subscription-plans/{plan_id}/line-items/{subscription_plan_line_item_id}Idempotent

Removes one addressable line item from the active subscription plan template.

Path parameters

plan_idstringrequired

Flint subscription plan ID.

subscription_plan_line_item_idstringrequired

Stable subscription plan line item ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X DELETE https://api.withflintpay.com/v1/subscription-plans/plan_123/line-items/spli_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "plan_id": "plan_123",
    "name": "Monthly Membership",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "line_items": [
      {
        "subscription_plan_line_item_id": "spli_123",
        "name": "Membership",
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "quantity": 1
      }
    ],
    "status": "active",
    "metadata": {
      "segment": "gold"
    },
    "currency": "USD",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rate this doc