> ## Documentation Index > Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt > Use this file to discover all available pages before exploring further. # Subscriptions & Stripe > Understand Starfire AI subscription provisioning, Stripe customer linkage, webhooks, reconciliation, plan changes, and customer portal behavior. # 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 That is why Billing 4.0 links Stripe state to a Starfire `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. Follow a structured checklist for plan and provisioning mismatches.