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

# Prepaid credit

> Sell credit up front, choose when VAT is charged, and top customers up automatically

Prepaid credit is credit a customer pays for before they use it: "buy ₦20,000 of credit, spend it on API calls". Their usage invoices then spend the credit before charging the card.

## Sell credit

Sell a **credit pack** (a one-time price on a product created with `kind: credit`) or a custom amount:

```bash theme={null}
curl https://bouclay.com/api/v1/customers/ctm_…/credit-purchases \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: topup-ctm-123-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 20000, "vatTiming": "at_redemption", "expiresAfterMonths": 12}'
```

It issues a top-up invoice (`billingReason: credit_purchase`). Its credit waits as `pending_payment`, shown in `pending` on the balance, until the invoice is paid; then it becomes spendable and its expiry starts.

* With manual collection (the default), send the customer to the invoice's `hostedUrl` to pay.
* With `"collectionMode": "automatic"`, Bouclay charges `paymentMethod`, or the customer's default card.
* Voiding an unpaid top-up cancels its credit.

### Bonus packs

"Pay ₦50,000, get ₦55,000": set `creditAmount` above `unitAmount` on the pack's price. The extra ₦5,000 is its own promotional lot, spent first. Refunding or charging back the top-up forfeits what is left of the bonus.

## When VAT is charged

The customer pays VAT once on what their credit pays for. You choose when, with `vatTiming` on the purchase, the pack's product, or your default under **Billing settings → Tax → Prepaid credit**. Which one fits is a question for your accountant.

| `vatTiming` | The top-up | When credit is spent |
| - | - | - |
| `at_redemption` | Carries no VAT, and is numbered in its own `-PP-` sequence. | After tax, like cash. ₦12,000 of usage is ₦12,900 with VAT; ₦10,000 of credit leaves ₦2,900 to charge. |
| `at_purchase` | A normal tax invoice: ₦10,000 + ₦750 VAT. | Before tax, so the usage it covers isn't taxed again. ₦12,000 of usage leaves ₦2,000 + ₦150 VAT. |

Credit taxed when bought only pays lines taxed the same way as its top-up. An exempt, zero-rated or export line, or one after a VAT rate change, is billed normally.

## Refunds

Refunding a top-up is capped at the credit not yet spent (for `at_purchase` credit, that credit plus its VAT). A credit note on a usage invoice that prepaid credit paid gives that part back to the lots it came from.

## Stop when credit runs out

Read `projectedAvailable` on the [credit balance](https://docs.bouclay.com/credits/overview.md#read-what-a-customer-has) before costly work, and stop at zero. For an exact stop, with no overspend when two requests arrive at once, use [credit holds](https://docs.bouclay.com/credits/holds.md).

## Auto-reload

Keep a customer topped up: "when my credit falls to ₦5,000, buy ₦20,000 with my card".

```bash theme={null}
curl https://bouclay.com/api/v1/customers/ctm_…/credit-auto-reloads \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: autoreload-ctm-123-ngn" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 5000, "amount": 20000}'
```

* One rule per customer and currency. Posting again replaces it.
* After every change to the customer's credit and every usage event, Bouclay compares `projectedAvailable` with `threshold`. At or below it, it buys `amount` of prepaid credit, charged to `paymentMethod` or the default card.
* One fall buys once. It buys again only after the credit has been back above the threshold.
* `PATCH /customers/{id}/credit-auto-reloads/{currency}` changes it; `"enabled": false` turns it off.

If a charge fails, that top-up is voided, the rule turns itself off (`disabledReason: payment_failed`), and the customer gets an email saying automatic top-ups are off. Nothing is retried. Turn it back on once the card is sorted. A rule also turns itself off when there is no card left to charge (`no_payment_method`). Each change sends `credit_auto_reload.updated`.


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