Subscriptions & Stripe
Stripe is the payment processor behind Starfire’s subscription billing, while Starfire remains the source of truth for product identity, entitlement, organization context, and feature access.Why Starfire keeps its own billing model
A payment processor knows about customers, prices, invoices, and subscriptions. Starfire also needs to know:- which user or organization owns the subscription
- which plan the subscription maps to
- which credits and features should be provisioned
- which seats or organization rules apply
- whether entitlement state is current
BillingAccount rather than treating Stripe alone as the application database.
Subscription lifecycle
A subscription can move through states including creation, activation, plan change, renewal, cancellation, payment failure, and end-of-service according to Stripe and Starfire configuration. Starfire reacts to those changes through webhook and reconciliation logic.Idempotent webhook handling
Stripe may deliver the same event more than once. Billing 4.0 is designed so processing an event repeatedly does not repeatedly grant credits, duplicate subscriptions, or re-run provisioning.Transactional provisioning
Where product access changes because of a billing event, related Starfire updates should be applied together so the user is not left in a partially provisioned state.Reconciliation
Reconciliation compares stored Starfire billing state with Stripe and repairs mismatches when possible. This matters when:- a webhook was delayed
- a temporary backend error interrupted processing
- an administrator changed billing state
- a customer portal action happened outside the normal app flow
Plan and seat changes
Supported upgrades, downgrades, and seat changes should operate on the current subscription relationship where possible. Starfire then recalculates entitlements from the resulting subscription and plan configuration.Customer portal
The Stripe customer portal can provide secure access to supported payment-method and subscription actions. Starfire should open the portal for the correct linked customer and billing context.Troubleshooting principle
If Stripe and Starfire disagree, do not create a second subscription just to force access. Identify whether the mismatch is in customer linkage, subscription state, price mapping, webhook processing, reconciliation, or entitlement provisioning.Billing troubleshooting
Follow a structured checklist for plan and provisioning mismatches.