A subscription connects a customer to a recurring price and a billing period. It may begin immediately or after a trial.

​
Lifecycle

The normal lifecycle is trialing → active → past_due or cancelled. A subscription can also be paused or incomplete while customer action is required. Handle state transitions from signed events. Do not grant or remove access only because a customer returned from checkout.

​
Changes

Use explicit update operations for plan changes, quantities, discounts, pause/resume, and cancellation. Decide whether cancellation happens immediately or at the end of the current period and communicate that choice to the customer.

​
Failed payments

Listen for invoice payment failures, notify the customer, and provide a self-service path to update payment details. Keep access and entitlement decisions idempotent as invoices are retried or later paid.