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

# Top-ups

> Refill a credit balance — manually, automatically, or by package — following the customer's collection method.

A **top-up** adds credits to a customer's [wallet](/documentation/credits/wallets-and-ledger) outside the normal plan refill — the customer is running low and wants more now. UnitPay grants the credits and settles the money; the only question is *how* the money moves.

## How a top-up settles

A self-serve customer has a saved payment method, so a top-up charges it right away:

1. **Charge** the saved card via the PSP for the top-up amount.
2. **Grant** the credits once the charge succeeds.

Money in, then credits out — the balance reflects the purchase immediately. If no card is on file yet, the charge collects one in the browser first (the same [card-on-file flow](/documentation/billing#collecting-the-first-card) a subscription uses), then grants.

## Auto top-ups

Auto top-ups make the refill automatic: when a balance falls below a threshold after a usage event, UnitPay purchases more credits without the customer lifting a finger — preventing service interruptions for customers who don't want to manage a balance by hand.

You configure a per-feature threshold and a quantity to purchase (`PUT /v1/customers/:id/auto-topup-rules/:creditCurrencyId`); the charge hits the saved card. Purchase limits cap runaway spend, and burst suppression prevents duplicate purchases from rapid-fire usage.

## Credit packages

A **credit package** is a pre-defined bundle of credits a customer buys as a self-serve top-up (priority 50 in the [grant convention](/documentation/credits/grants-and-priority) — preserved behind plan credits as a buffer). Packages are the manual counterpart to auto top-ups: the customer picks a bundle and checks out, and the same `collectionMethod` branch decides charge-now vs. invoice.

For a \$-denominated wallet, a package is priced so one credit equals one minor currency unit — see [Denominations](/documentation/credits/denominations).

## In your app

The [React credit hooks](/react/introduction) cover the whole top-up surface — reading balances, buying a package, triggering a top-up, configuring auto top-ups, and showing history.

## See also

<CardGroup cols={2}>
  <Card title="Grants & priority" icon="layer-group" href="/documentation/credits/grants-and-priority">
    Where package credits sit in the deduction order.
  </Card>

  <Card title="Wallets & the ledger" icon="wallet" href="/documentation/credits/wallets-and-ledger">
    How a top-up lands as a grant on the wallet.
  </Card>

  <Card title="Denominations" icon="coins" href="/documentation/credits/denominations">
    Unit vs. fiat — and which top-up route applies.
  </Card>

  <Card title="Billing" icon="credit-card" href="/documentation/billing">
    The card-on-file flow a top-up reuses.
  </Card>
</CardGroup>