Billing Troubleshooting

Resolve Starfire AI plan, Stripe, subscription, provisioning, and billing-account issues.

Billing troubleshooting

Use this guide when Stripe payment state and Starfire product access do not agree.

The central rule is: diagnose the billing chain before creating another subscription or manually granting permanent access.

Billing chain

User / Organization
        ↓
BillingAccount
        ↓
Stripe Customer
        ↓
Subscription
        ↓
Price mapping
        ↓
Starfire Plan
        ↓
Entitlements + Credits

A mismatch anywhere in that chain can make the UI look like “the plan did not attach.”

Payment succeeded but plan did not update

1. Confirm the user is signed into the same Starfire account that initiated checkout.
2. Confirm checkout used the intended personal or organization context.
3. Check whether the billing account is linked to the expected Stripe customer.
4. Check the subscription and price mapping.
5. Check webhook processing.
6. Run or inspect reconciliation state where available.
7. Verify the resulting Starfire plan and entitlements.

Do not immediately start a second checkout.

Wrong organization has the subscription

Determine which billing context created checkout. Personal and organization billing accounts are separate.

If the subscription was created under the wrong context, treat it as an ownership/billing correction problem rather than hiding the mistake with manual feature grants.

Upgrade or downgrade not reflected

Check whether Stripe shows the changed subscription state, whether Starfire received/reconciled it, and whether the current plan mapping produced the expected entitlements.

A plan change can also alter credits, models, storage, FORGE/research access, seat limits, or retention rules—not just the label shown in the UI.

Customer portal does not open

Confirm the active billing context has a linked Stripe customer and that the portal action is being created for that customer.

Duplicate subscription concern

If a user believes they were billed twice, first determine whether two Stripe subscriptions exist, two different billing contexts were used, or the visible transaction is something else.

Do not infer duplicate billing from two Starfire UI records alone.

Webhook failure

Billing 4.0 uses idempotent event processing so retrying the same Stripe event should not duplicate provisioning.

If an event failed, investigate processing and reconciliation rather than manually replaying unrelated state changes.

Credits are wrong after renewal

Check the billing period, plan allowance, reconciliation state, and whether usage/credit provisioning for the new period completed.

Manual credit adjustment can be appropriate only when authorized and should remain auditable. It should not replace fixing the underlying renewal/provisioning issue.

Administrator checklist

Before changing access manually, confirm:

• correct BillingAccount
• correct Stripe customer
• correct subscription
• correct price → plan mapping
• webhook/reconciliation state
• resulting entitlements
• current credit period and allowance

Never request or record full card details in Starfire support notes or admin diagnostics. Payment-sensitive data should remain inside the payment provider’s supported surfaces.

Billing & plans

Review the Billing 4.0 model.

Billing administration

See the Control Center operator workflow.