Billing

Credit notes & credit balance

Hold a credit balance for a customer and apply it automatically to future invoices.
View as Markdown

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

ConceptWhat it is
Credit noteA single ledger entry: credit issued, applied to an invoice, or voided.
Credit balanceThe sum of all credit notes for a customer in a given currency.

You can work at either level:

  • Set a balance directly with PATCH credit-balance — PaymentKit computes the difference and issues or voids credit to reach your target.
  • 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.

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.

  1. Open the Customer
  2. Open the Credit balance panel
  3. Enter the new balance and currency
  4. Click Save
FieldTypeDescription
amount_atomintegerThe target balance in the smallest currency unit (e.g. cents). A positive value is credit owed to the customer.
currencystringCurrency code (e.g. USD). Each currency’s balance is independent.

The response is the resulting balance:

1{ "amount_atom": 5000, "currency": "USD" }

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://api.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"
>}'
FieldTypeDescription
amount_atomintegerCredit amount in the smallest currency unit. Must be greater than 0.
currencystringCurrency code (e.g. USD).
reasonstringOne of proration_excess, manual_adjustment, auto_apply, debit_settlement.
memostringOptional human-readable note (max 500 chars).
invoice_idstringOptionally link the note to an existing invoice. If omitted, a fully-paid companion invoice is created to back the credit.

Send an Idempotency-Key header so a retried request doesn’t issue the credit twice.

The credit note object

1{
2  "id": "cn_live_1a2b3c4d5e6f7g8h",
3  "customer_id": "cus_live_...",
4  "invoice_id": "in_live_...",
5  "amount_atom": 2500,
6  "currency": "USD",
7  "type": "issued",
8  "reason": "manual_adjustment",
9  "memo": "Goodwill credit for billing error",
10  "created_at": "2026-06-17T14:00:00Z",
11  "updated_at": "2026-06-17T14:00:00Z"
12}
FieldDescription
idCredit note identifier, prefixed cn_.
typeissued (credit added), applied (consumed by an invoice), or voided (reversed).
amount_atomPositive when credit is issued; negative when applied or voided.
invoice_idThe invoice the note is linked to, if any.

List a customer’s credit notes

$curl "https://api.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.

How credit is applied

When an invoice is collected, 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.

The current balances are also exposed on the customer object:

1{
2  "id": "cus_live_...",
3  "credit_balances": [
4    { "amount_atom": 5000, "currency": "USD" },
5    { "amount_atom": 1200, "currency": "EUR" }
6  ]
7}

credit_balances lists every non-zero balance by currency and is the field to read. The legacy singular credit_balance is retained for backward compatibility and reflects only the largest balance.

Webhook events

The subscribable webhook for credit activity is customer.updated, which fires whenever a customer’s cached credit balance is refreshed (after credit is issued, applied, or voided).

EventTrigger
customer.updatedA customer’s cached credit balance was refreshed.

Credit-note ledger writes emit an internal credit_note.created event, but credit_note.* events are not currently exposed as subscribable webhooks. Track credit changes via customer.updated or by reading credit_balances on the customer.