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

# Credit and balances

> Money a customer can spend on their next invoices: balance, promotional credit and prepaid credit

A customer can hold three kinds of credit. Each one pays part of their next invoices before Bouclay charges the rest.

| Kind | Where it comes from | When it is spent |
| - | - | - |
| **Customer balance** | Money owed back to the customer, such as a credit note to `balance`, or unused time after a downgrade. | After tax, like a payment. |
| **Promotional credit** | Credit you give from your own margin: a launch offer, goodwill after an outage. | Before tax, like a discount, so it lowers the VAT too. |
| **Prepaid credit** | Credit the customer paid for up front. See [Prepaid credit](https://docs.bouclay.com/credits/prepaid-credit.md). | Before or after tax, depending on when you charge VAT. |

All credit is per currency. Credit in naira only pays naira invoices. Card verification charges and payment-link checkouts never spend credit.

## Read what a customer has

```bash theme={null}
curl https://bouclay.com/api/v1/customers/ctm_…/credit-balance \
  -H "Authorization: Bearer $BOUCLAY_KEY"
```

One entry per currency:

| Field | Means |
| - | - |
| `available` | What the next invoice will take before charging the rest. |
| `balance` | The money balance alone. Negative when the customer owes a carried amount (below). |
| `grants` | Each active lot of promotional or prepaid credit, with what is left and when it expires. |
| `pending` | Prepaid credit bought but not yet paid for. |
| `unbilled` | What usage so far in the open periods would draw at the end of those periods. |
| `held` | What open [credit holds](https://docs.bouclay.com/credits/holds.md) would take. |
| `projectedAvailable` | `available` less `unbilled` and `held`: what would be left if usage stopped now. Compare it with zero before serving a request. |

Refresh it when you get `credit_grant.created`, `credit_grant.updated` or `invoice.updated`.

## Customer balance

The balance is money that belongs to the customer. Invoices spend it after tax, and the invoice shows it as `balanceApplied`. Voiding an invoice gives its `balanceApplied` back.

It grows when you issue a credit note with `destination: balance`, or when a downgrade with `prorationBehavior: always` credits unused time.

### Small amounts carried forward

Card gateways have a smallest amount they will charge. Bouclay never sends a charge below it (or below a higher minimum you set per currency under **Billing settings → Currencies**). Instead the invoice is marked paid from the balance and the amount is carried to the customer's next invoice in that currency, where it reads "Carried from INV-0003". While it waits, `balance` is negative and `available` is 0.

## Promotional credit

Give credit with `POST /credit-grants`:

```bash theme={null}
curl https://bouclay.com/api/v1/credit-grants \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: goodwill-ctm-123-oct" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "ctm_…",
    "amount": 2000,
    "reason": "Sorry for the outage on 12 October",
    "expiresAt": "2027-01-31T23:59:59Z"
  }'
```

Each grant is a **lot** (`cg_…`) with its own expiry. It is spent before tax, so it lowers the VAT like a discount: ₦12,000 of usage with ₦2,000 of credit is ₦10,000 + ₦750 VAT = ₦10,750. The invoice shows it as `grantApplied`.

* Lots are spent soonest expiry first, then oldest. At the same expiry, promotional credit goes before prepaid.
* When a lot expires, what was left is gone: `remaining` reads 0 and `credit_grant.updated` follows within the hour.
* Voiding an invoice gives back what it spent. A credit note can't give promotional credit back.

`GET /credit-grants/{id}` lists every movement on a lot (the grant, each invoice that spent part of it, voids and expiry), so you can answer "where did my credit go?". Customers can see their credit in the portal too.


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