> ## 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.

# Billing Reconciliation Runbook

> Reconcile Starfire AI BillingAccount, Stripe customer, subscription, price mapping, entitlements, credits, and organization seats without creating duplicate state.

# 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.

<Warning>
  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.
</Warning>