A customer’s credit balance is money you owe them, held against their account. PaymentKit applies it automatically when their next invoice is collected. Each adjustment to the balance is recorded as a credit note — an immutable ledger entry — so the balance is always the running sum of every note.

Balances are tracked per currency. A customer can hold credit in USD and EUR independently.

Credit balance vs. credit notes

You can work at either level:

• Raise a balance to an absolute target with PATCH credit-balance — PaymentKit computes the difference against the current balance and posts it to the ledger.
• Lower a balance with POST credit-balance/reduce — you state how much to take off rather than what the balance should end up as. This is the endpoint to use for reductions.
• Append a specific credit note with POST credit-notes — useful when you want a reason and memo on record, or to link the credit to a specific invoice. This endpoint only ever adds credit; it cannot reduce a balance.

Set a customer’s credit balance

PATCH credit-balance sets the balance to an absolute target, not a delta. PaymentKit compares your target against the current balance and issues credit (if higher) or voids credit (if lower) to match.

The response is the resulting balance. Currency codes come back lowercase:

{ "amount_atom": 5000, "currency": "usd" }

Reduce a customer’s credit balance

POST credit-balance/reduce removes a stated amount of credit and returns the ledger entry that records it. You say how much to take off, not what the balance should end up as, so the request means the same thing no matter what else moved the balance in the meantime.

curl -X POST https://app.paymentkit.com/api/{account_id}/customers/{customer_id}/credit-balance/reduce \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: expiry-sweep-2026-06" \
-d '{
  "amount_atom": 2500,
  "currency": "USD",
  "reason": "expiry_clawback",
  "memo": "Unused promo credit from the May campaign"
}'

The response is 201 with the credit note that was written — a voided entry with a negative amount_atom — plus balance_after_atom, the balance the write left behind, read in the same transaction so a sweep need not re-read:

{
  "id": "cn_live_1a2b3c4d5e6f7g8h",
  "customer_id": "cus_live_...",
  "invoice_id": null,
  "amount_atom": -2500,
  "currency": "usd",
  "type": "voided",
  "reason": "expiry_clawback",
  "memo": "Unused promo credit from the May campaign",
  "created_at": "2026-06-17T14:00:00Z",
  "updated_at": "2026-06-17T14:00:00Z",
  "balance_after_atom": 7500
}

Store that cn_ id to correlate the reduction later. No companion invoice is created — reclaiming unused credit is a ledger correction, not a document the customer receives — so invoice_id is null.

It refuses rather than clamps

A reduction larger than the balance is rejected with 409 credit_balance_insufficient, not trimmed to zero. Balances here can legitimately go negative — a negative balance is a debit added to the customer’s next invoice — so reducing past zero would overcharge them.

Errors

The two business refusals and the validation 422 use the RFC 7807 field set (served as application/json): the human-readable text is detail, and the machine-readable fields — error_code and the balance figures — sit at the top level of the body next to it, the same shape as collection_in_progress on invoices. The one exception is the in-flight duplicate 409 below, which is a bare {"detail": "..."}.

{
  "type": "about:blank",
  "title": "Credit Balance Insufficient",
  "status": 409,
  "detail": "Cannot reduce a credit balance below zero. The customer holds 1000 and you asked to remove 2500.",
  "instance": "https://app.paymentkit.com/api/acc_live_.../customers/cus_live_.../credit-balance/reduce",
  "request_id": "be_prod_...",
  "error_code": "credit_balance_insufficient",
  "current_balance_atom": 1000,
  "requested_amount_atom": 2500,
  "currency": "usd"
}

Three conditions share 409 and their remedies differ, so branch on error_code, not on the status.

Idempotency

Send a stable Idempotency-Key header of at least 8 characters (shorter is rejected with 422). A duplicate that arrives while the first request is still in flight is refused with the 409 above, for up to five minutes. Once the first request has completed, its response is replayed for the same (key, account, endpoint) — and on this endpoint the endpoint half carries the customer id, see the note below — instead of running again. The replay record is written in the same transaction as the ledger entry, so once the reduction is committed a retry gets the stored result, never a second reduction. If the process dies before that commit, nothing was written and a retry applies for the first time — which is what you want, though an early retry sees the in-flight 409 until that five-minute claim lapses.

Replay is guaranteed for 24 hours; don’t rely on it beyond that, and never reuse a key for a genuinely new reduction — note that a refusal (4xx) is replayed too. Reconcile against GET credit-notes when in doubt.

If a response is ambiguous and you sent no idempotency key, don’t blind-retry. Read GET credit-notes — the ledger, not the customer’s cached balance — to see whether the entry landed.

Issue a credit note

POST credit-notes appends a credit to the customer’s balance with a reason and optional memo.

curl -X POST https://app.paymentkit.com/api/{account_id}/customers/{customer_id}/credit-notes \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: credit-overcharge-918" \
-d '{
  "amount_atom": 2500,
  "currency": "USD",
  "reason": "manual_adjustment",
  "memo": "Goodwill credit for billing error"
}'

The credit note object

{
  "id": "cn_live_1a2b3c4d5e6f7a8b",
  "customer_id": "cus_live_...",
  "invoice_id": "in_live_...",
  "amount_atom": 2500,
  "currency": "USD",
  "type": "issued",
  "reason": "manual_adjustment",
  "memo": "Goodwill credit for billing error",
  "created_at": "2026-06-17T14:00:00Z",
  "updated_at": "2026-06-17T14:00:00Z",
  "expires_at": null,
  "expired_at": null,
  "remaining_atom": null
}

Reasons split three ways: some you set when issuing credit, some you set when reducing a balance, and some PaymentKit writes for itself.

When an invoice is voided

If an invoice that had credit applied to it is voided because the amount was never genuinely owed — a plan-change proration, or a merchant voiding an invoice raised in error — that credit returns to the customer’s balance automatically as a void_reversal note. You don’t need to issue a compensating credit note yourself in that case; doing so would double-credit the customer.

Credit is not returned when the write-off ends a collection that was attempted and failed. An invoice that exhausted dunning keeps the credit consumed whether it ends up void or uncollectible — the customer owed that money and did not pay it, so the merchant absorbs the net rather than the gross. Which of the two labels dunning applies is your invoice_status_on_failure setting, and it affects your books only, never the customer’s balance.

The same holds for uncollectible: writing a debt off never returns the credit it consumed. If you then void that same invoice yourself, the credit does come back — once, from the void.

If the invoice instead settled a negative (debit) balance, voiding it re-instates that debit as a void_reversal note with a negative amount, since the customer never paid it. So a void_reversal can move the balance in either direction — read its amount_atom rather than assuming credit was added.

The returned credit can arrive as more than one note:

• If the customer holds no expiring credit in that currency, it is a single void_reversal note with no expires_at.
• Otherwise there is one note per expiring credit note the invoice drew on, each carrying that note’s own expires_at, plus at most one further note with no expires_at for the remainder. Voiding never turns expiring credit into permanent credit, and if a date has already passed the restored credit is already expired — PaymentKit reclaims it on the next pass.

However they are split, the notes always sum to exactly what the ledger says the invoice consumed.

List a customer’s credit notes

curl "https://app.paymentkit.com/api/{account_id}/customers/{customer_id}/credit-notes?currency=USD" \
  -H "Authorization: Bearer sk_live_..."

Pass an optional currency filter; results are paginated and sorted newest-first.

Two more filters help with expiring credit:

Combine them to see what is about to be reclaimed: ?unused_only=true&expires_before=2026-10-01T00:00:00Z.

How credit is applied

When an invoice is finalized, PaymentKit automatically draws down any available credit in the invoice’s currency. Each application writes an applied credit note with a negative amount, and the balance falls accordingly. You don’t need to apply credit manually — issuing it is enough.

Credit issued after an invoice was finalized can still reach that invoice, but each invoice draws at most once. While nothing has been applied to it, a payment retry on an open or past-due invoice applies whatever balance is available at that point. Once credit has been applied or a debit settled, later retries leave that invoice alone and the credit stays on the customer’s balance for the next one.

An invoice only ever draws on credit that has not expired, and it takes the soonest-expiring credit first — so expiring credit is spent ahead of credit that never expires, and ahead of the reclaim. Credit whose expires_at has already passed is skipped even in the window before PaymentKit reclaims it, so what an invoice can draw is sometimes less than the balance below. See Expiring credit.

Only credit still on the balance can be drawn down, so a reduction posted before an invoice collects lowers what that invoice can take. A reduction never rewrites an application that already happened — it appends a voided note of its own, and invoices already collected are untouched.

The current balances are also exposed on the customer object:

{
  "id": "cus_live_...",
  "credit_balances": [
    { "amount_atom": 5000, "currency": "USD" },
    { "amount_atom": 1200, "currency": "EUR" }
  ]
}

Expiring credit

Set expires_at when you issue a credit note and PaymentKit handles the rest:

1. Invoice spending stops at the instant expires_at passes. An invoice finalized one second later will not draw on that credit, even before it has been reclaimed. Credit issued without an expires_at is unaffected.
2. The unused remainder is reclaimed shortly after, by a sweep that runs every 15 minutes by default. Treat the reclaim as prompt, not as a deadline — what is guaranteed is that the credit stops being spendable at expires_at. The sweep sets expired_at on the original note, writes a voided credit note with reason credit_expired for whatever it reclaims, and emits a credit_note.expired event carrying issued_atom, remaining_before_atom (what the note still held), clawed_back_atom (what was actually taken), expires_at, expired_at and currency.
3. The reclaim never takes more than the customer’s balance, and never takes credit that has not expired. So clawed_back_atom can be less than remaining_before_atom — including 0, for a customer whose balance is at or below zero, or whose balance is only positive because of other credit that is still valid. The event still fires in those cases; reconcile on clawed_back_atom, not on remaining_before_atom. When the reclaim takes 0 no credit_expired note is written at all — only expired_at is set.
4. A note that was fully used before its date is closed out silently: expired_at is set, nothing is reclaimed, and no credit_note.expired event is emitted.
5. remaining_atom tells you what is still unused on each expiring credit note. It is not the same as spendable: between expires_at passing and the reclaim it still reports a value the customer can no longer apply, and it reads 0 once the note is closed out, whatever the reclaim was able to take.

Everything above is per currency. A customer’s balance, their expiring credit and each reclaim are tracked separately for each currency they hold credit in.

When an invoice that drew on expiring credit is voided, the credit comes back with the same expires_at it had. Voiding an invoice never turns expiring credit into permanent credit — and if that date has already passed, the restored credit is already expired: it cannot be applied, and PaymentKit closes it out on a following sweep, reclaiming whatever point 3 allows.

Webhook events

The subscribable webhook for credit activity is customer.updated. It fires whenever a customer’s cached credit balance is refreshed: after credit is issued, applied, voided, reduced, or reclaimed at expiry.

To track credit changes, subscribe to customer.updated and read credit_balances from the customer object on the API. The webhook payload is the stored customer row, so data.object carries the raw credit_balance cache ({currency: amount_atom}), not the credit_balances array.

A customer.updated on its own does not mean the balance moved: the reclaim pass refreshes the cache for every credit note it closes out, including one that was already fully used. Compare the balance against what you last stored.

credit_note.created fires in both directions

Every ledger write emits credit_note.created — including the writes that take credit away. Subscribe to it and you receive both directions on the same event name. It is also visible in the account’s event log (GET /api/{account_id}/events/), and the same rule applies to what you read back from GET credit-notes: reducing a balance appends an entry just as issuing one does, so the event name alone never tells you which happened. Read the entry before assuming credit was granted.

The sign of amount_atom is the reliable signal. reason narrows it but does not settle it: manual_adjustment is written in both directions, and a void_reversal can go either way. Only expiry_clawback is exclusive to a reduction — the reduce endpoint is the only place that accepts it, and issuing a credit note with that reason is rejected.

A reduction writes only the ledger entry. Unlike issuing a credit note with no invoice_id, it creates no companion invoice, so no invoice.created accompanies it.