FlintflintDocs

Subscriptions

Subscriptions link a customer to a subscription plan and automate recurring billing. Create one directly when you already have a Flint customer_id and a usable payment method for that customer; for Flint-hosted signup, sell the plan through a checkout session or payment link with plan_id instead.

Non-trial subscriptions start as incomplete while Flint collects the first paid period, then move to active; grant access only once the subscription is active. From there, the lifecycle covers trialing, paused, past_due, and canceled. Pausing preserves remaining prepaid time, cancellation can take effect immediately or at period end, and failed renewals enter dunning, where Flint retries the payment before applying your configured end action. Flint prevents duplicate non-canceled subscriptions for the same customer and plan.

See the Subscription billing guide for the full lifecycle and dunning behavior. Use webhooks like subscription.activated and subscription.past_due to drive entitlement changes.

Endpoints

List subscriptions#

GET/v1/subscriptions

Returns a paginated list of subscriptions 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 status.

trialingactivepausedpast_duecanceledincomplete
customer_idstring

Filter by Flint customer ID.

plan_idstring

Filter by Flint subscription plan ID.

querystring

Search across customer name/email and plan name.

sort_byenum

Sort field.

created_atupdated_atnext_billing_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

next_billing_at_afterstring

RFC3339 lower bound for next_billing_at.

next_billing_at_beforestring

RFC3339 upper bound for next_billing_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "subscription_id": "sub_123",
      "plan_id": "plan_123",
      "customer_id": "cus_123",
      "payment_method_id": "pm_123",
      "status": "active",
      "billing_anchor_day": 15,
      "cancel_at_period_end": false,
      "current_period_start": "2026-03-17T14:30:00Z",
      "current_period_end": "2026-04-17T14:30:00Z",
      "next_billing_at": "2026-04-17T14:30:00Z",
      "metadata": {
        "source": "api"
      },
      "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#

POST/v1/subscriptionsIdempotent

Creates a subscription for the authenticated merchant.

Request body
billing_anchor_dayinteger
customer_idstringrequired
metadatamap of string
payment_method_idstring
plan_idstringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "billing_anchor_day": 15,
    "metadata": {
      "source": "api"
    }
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "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#

GET/v1/subscriptions/{subscription_id}

Returns a single subscription by ID.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Query parameters
expandarray of enum

Supported expansions: customer, payment_method, subscription_plan. Expansion requires commerce.subscriptions.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=customer&expand=payment_method. Comma-separated values, expand[]=customer, and numeric expand[0]=customer are accepted for common client compatibility.

customerpayment_methodsubscription_plan
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/subscriptions/sub_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update subscription#

PATCH/v1/subscriptions/{subscription_id}Idempotent

Updates mutable subscription fields such as payment_method_id and metadata.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
cancel_at_period_endboolean
metadatamap of string
payment_method_idstring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/subscriptions/sub_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "payment_method_id": "pm_456",
    "metadata": {
      "source": "customer_portal"
    }
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "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"
}

Cancel subscription#

POST/v1/subscriptions/{subscription_id}/cancelIdempotent

Cancels a subscription immediately or at period end. Response may include advisory contract information.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
cancel_immediatelyboolean
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "cancel_immediately": false
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": true,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-20T10:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Pause subscription#

POST/v1/subscriptions/{subscription_id}/pauseIdempotent

Pauses a subscription immediately, optionally for a fixed number of billing cycles.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Request body
pause_duration_cyclesinteger
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_123/pause \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "pause_duration_cycles": 2
  }'
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "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"
}

Resume subscription#

POST/v1/subscriptions/{subscription_id}/resumeIdempotent

Resumes a paused subscription.

Path parameters
subscription_idstringrequired

Flint subscription ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_123/resume \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "subscription_id": "sub_123",
    "plan_id": "plan_123",
    "customer_id": "cus_123",
    "payment_method_id": "pm_123",
    "status": "active",
    "billing_anchor_day": 15,
    "cancel_at_period_end": false,
    "current_period_start": "2026-03-17T14:30:00Z",
    "current_period_end": "2026-04-17T14:30:00Z",
    "next_billing_at": "2026-04-17T14:30:00Z",
    "metadata": {
      "source": "api"
    },
    "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