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

# Failed Payments & Billing Holds

> Understand how Starfire AI handles payment failures, retry/recovery state, billing holds, and product access without confusing billing with account security.

# Failed payments & billing holds

A payment failure is a billing problem, not automatically a security incident or account deletion event.

## What can happen

Depending on the active billing configuration, a failed payment can lead to:

* payment retry attempts
* customer notifications
* subscription status changes
* temporary grace behavior
* a billing-specific access hold
* eventual entitlement reduction or cancellation

## Billing hold

Starfire's account-state model supports the idea of a `BILLING_HOLD`-style condition so billing problems can be represented separately from suspension or security holds.

The exact access restrictions during a billing hold are controlled by current product policy.

## Recover

1. Open the supported billing/customer portal surface.
2. Review the subscription and payment-method state.
3. Update payment information when required.
4. Complete any provider-required recovery action.
5. Allow webhook/reconciliation processing to update Starfire.
6. Refresh the billing page and confirm entitlements.

## If payment succeeds but access remains restricted

Check reconciliation rather than paying again. The billing chain can lag or fail independently after the payment processor accepts a recovery payment.

## Organization subscriptions

For organization billing, failed-payment behavior can affect team entitlements. Organization owners/admins should investigate promptly because many members can depend on one subscription.

## Administrators

Operators should inspect billing-account state, Stripe subscription/invoice state, webhook processing, reconciliation, and resulting entitlements before manually lifting a hold.

<Warning>
  Do not convert a billing hold into a security suspension unless there is a separate security reason. Keep operational causes distinguishable.
</Warning>