> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# bead automatic credit refill

> Set up bead automatic credit refill with a saved card and recover failed payments.

You need admin scope and a card authorized for future payments before enabling bead automatic credit refill. Saving a card and enabling refill are separate steps.

## Save a card

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead billing autorefill save-card
```

Open the returned hosted setup link and complete card authentication. Stripe stores the card; bead stores its provider identifiers.

## Configure refill

Set `REFILL_THRESHOLD_CENTS`, `REFILL_AMOUNT_CENTS`, and `REFILL_MONTHLY_CAP_CENTS` to your chosen threshold, refill amount, and monthly cap in whole cents in the billing currency.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead billing autorefill show
bead billing autorefill set --enabled --threshold "$REFILL_THRESHOLD_CENTS" --amount "$REFILL_AMOUNT_CENTS" --monthly-cap "$REFILL_MONTHLY_CAP_CENTS"
```

Refill triggers when the settled balance crosses below your threshold. The refill amount must fit within the configured calendar-month cap. Months use UTC.

Pending, failed, and successful attempts count conservatively against the monthly cap. Refunds do not restore that allowance. Reservations alone do not lower the balance or trigger a crossing.

Enabling refill while the settled balance is already below the threshold also evaluates the balance and can queue a refill immediately.

To disable new automatic refills, omit `--enabled`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead billing autorefill set --threshold "$REFILL_THRESHOLD_CENTS" --amount "$REFILL_AMOUNT_CENTS" --monthly-cap "$REFILL_MONTHLY_CAP_CENTS"
```

An already queued collection retains its original authorization.

## Recover a failed payment

Declines or authentication requirements pause automatic refill. There is no automatic card retry.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead billing autorefill recover
```

Complete the returned hosted Checkout flow for the failed purchase. Recovery requires enough quote lifetime; otherwise make a [normal top-up](https://docs.bead.run/platform/top-up.md). Save or replace the card if needed, then explicitly enable automatic refill again.

A monthly-cap pause also needs explicit resumption after the cap increases or the month changes. Funded deadlines still apply while payment is pending or refill is paused. Check [balance](https://docs.bead.run/platform/prepaid-credit.md) before continuing work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.