Model a subscription as state, not a Boolean A subscription can be trialing, active, past due, canceled at period end, paused, or expired. A single is_paid...
Model a subscription as state, not a Boolean
A subscription can be trialing, active, past due, canceled at period end, paused, or expired. A single is_paid flag cannot describe those transitions or tell the application whether a user should retain access during a payment retry. Start with a state diagram that matches the billing provider and the product's policy.
Separate billing state from entitlement state. A payment provider reports invoices and subscription events; your application decides which features the account can use. Those decisions should be documented, especially for grace periods, failed renewals, and cancellations.
Define the lifecycle before integrating checkout
Record the tenant, provider customer ID, provider subscription ID, plan, billing interval, current period end, scheduled cancellation, and last synchronized event. Keep provider identifiers unique. A checkout redirect is not proof that payment succeeded; use a verified provider webhook and a reconciliation path.
For each event, specify the expected local transition. An invoice paid event may extend access, while payment failure may begin a grace period. An out of order event should not move the account back to an older state. Compare provider event timestamps or fetch the authoritative subscription state when ordering is uncertain.
Make webhook processing idempotent
Providers retry webhooks. Verify the signature against the raw request body, persist the event ID with a unique constraint, and process it once. A worker can fail after applying one effect, so subscription transitions and any side effects need their own idempotency boundaries.
Return a successful response only after the event is safely accepted for processing. If processing is asynchronous, store the event durably before acknowledging it. Never trust a browser submitted "payment complete" flag to grant entitlement.
Handle upgrades, downgrades, and cancellation
Proration and billing date behavior vary by provider and configuration. Explain the effective time and next charge to users before they confirm a change. Decide whether downgrades apply immediately or at period end. When a plan loses a capability, preserve customer data unless the retention policy explicitly allows deletion.
Cancellation is not the same as immediate account deletion. Track whether access continues through the paid period, how data can be exported, and when retained data is eventually removed.
Reconcile and monitor
Webhooks can be delayed or missed during outages. Schedule reconciliation that compares local state to the provider for subscriptions changed recently or flagged as uncertain. Record differences for review instead of silently overwriting complex local state. Monitor failed webhook processing, unusually high payment failures, and accounts whose entitlement disagrees with billing.
Tests that matter
Test duplicate and out of order webhooks, a failed renewal, recovery after payment, an upgrade, a downgrade, scheduled cancellation, and a restored subscription. Verify both the stored state and feature access. Use provider test mode for integration checks; mocks alone cannot prove real event shape.
Conclusion
Reliable subscriptions require explicit states, verified events, idempotent processing, and reconciliation. These rules should be visible to support and billing staff, not buried in checkout code. The web and SaaS development service includes subscription architecture.
References