Credit and balances

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

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 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:

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.

Get started

Connect your app

Gateways

Catalog and subscriptions

Usage billing

Invoices and payments

Credits

Reporting

Credit and balances

Read what a customer has

Customer balance

Small amounts carried forward

Promotional credit

​Read what a customer has

​Customer balance

​Small amounts carried forward

​Promotional credit

Read what a customer has

Customer balance

Small amounts carried forward

Promotional credit