Subscription

A Subscription is a recurring charge agreement between a customer and the merchant. It binds a customer (identity_id) and a payment instrument to one or more priced items, and the billing engine generates invoices on each cycle and attempts collection automatically.

Lifecycle

1. incomplete — created without a usable instrument or before initial payment confirmation. Resolves to active once payment succeeds, or to incomplete_expired if it lapses.
2. trialing — created with trial_period_days or trial_end. No invoices are generated until the trial ends. Emits subscription.trial_will_end ahead of expiry.
3. active — invoices are generated at each current_period_end and charged against instrument_id. Emits subscription.created then subscription.updated on item, quantity, or status changes.
4. past_due / unpaid — payment failed. Dunning takes over (see Dunning config). Terminal action is governed by subscription_terminal_action.
5. paused — payment collection suspended via pauseSubscription. Emits subscription.paused; subscription.resumed on resume.
6. canceled — terminated by cancelSubscription (immediate) or cancel_at_period_end: true (deferred). Emits subscription.deleted once ended_at is set.

Relationships

A subscription belongs to a Customer (identity_id) and references a payment instrument (instrument_id). Each SubscriptionItem points at a Price which belongs to a Product. Generated Invoices are linked back via latest_invoice_id. Discounts attach via SubscriptionDiscount and reference a coupon or promotion code.

Fields that matter

• status (SubscriptionStatus) — drives billing behavior; one of incomplete, incomplete_expired, trialing, active, past_due, unpaid, canceled, paused.
• items (SubscriptionItem[]) — the priced lines that produce invoice line items each cycle. Mutate with addSubscriptionItem / updateSubscriptionItem / removeSubscriptionItem.
• current_period_start / current_period_end (ISO datetime) — bounds of the current billing window. Next invoice is generated at current_period_end.
• cancel_at_period_end (boolean) — when true, the subscription continues until current_period_end, then transitions to canceled.
• pause_collection ({ behavior, resumes_at } | null) — populated while paused; behavior controls how draft invoices during the pause are handled.
• pending_update (SubscriptionPendingUpdate | null) — staged item changes awaiting trial-end or next renewal.

Related

• API reference
• Guide: Create a subscription
• Guide: Apply a coupon