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. A subscription can start immediately, at a future time, or by importing an already-paid current period without charging.
A subscription is always in exactly one of six states:
status on subscriptionFinal values do not change againincompletesubscription.payment_succeeded.trialingactivepast_duepausedcanceledfinalNon-trial immediate 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 the owner-specific end action. A customer can hold multiple independent subscriptions to the same plan.
billing_schedule_owner is flint when Flint computes renewal dates and external when your integration supplies them. An external subscription with no next_billing_at keeps its lifecycle status and reports awaiting_billing_schedule: true; use the billing-schedule and skip-cycle endpoints to manage its timer. Past-due subscriptions can create idempotent, pollable manual payment retries.
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.