Billing reconciliation runbook
Use reconciliation when Stripe and Starfire disagree about subscription, plan, credits, seats, or entitlement state.
1. Confirm billing context
Identify whether the issue belongs to a personal BillingAccount or an organization BillingAccount.
2. Confirm Stripe customer linkage
Verify the BillingAccount points to the expected Stripe Customer and that checkout/portal operations use the same customer.
3. Inspect subscription state
Review:
- subscription status
- price/product identifiers
- quantity/seats where applicable
- current period
- cancellation state
- payment/invoice state
4. Validate price mapping
Confirm the Stripe price maps deterministically to the intended Starfire plan/configuration.
5. Review webhook history
Determine whether relevant Stripe events were received, processed successfully, retried, or rejected.
Idempotent processing should prevent duplicate provisioning when an event is delivered more than once.
6. Run/inspect reconciliation
Compare authoritative provider state with stored Starfire billing records and apply the supported reconciliation path.
7. Verify resulting entitlements
Confirm:
- displayed plan
- feature/model access
- credit allowance
- seat capacity
- billing hold state
- organization/shared billing behavior
8. Avoid compensating drift
Do not leave permanent manual plan grants or recurring credit adjustments in place just to hide a broken subscription mapping.
9. Audit manual corrections
When a manual correction is required, record the reason and supporting billing/incident context according to current audit capability.
Do not create a new subscription unless the user intentionally purchased another subscription. Reconciliation problems should be repaired within the existing billing relationship whenever possible.
