> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Credit notes & credit balance

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

| Concept            | What it is                                                                    |
| ------------------ | ----------------------------------------------------------------------------- |
| **Credit note**    | A single ledger entry: credit `issued`, `applied` to an invoice, or `voided`. |
| **Credit balance** | The 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**

```bash
curl -X PATCH https://api.paymentkit.com/api/{account_id}/customers/{customer_id}/credit-balance \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "amount_atom": 5000,
  "currency": "USD"
}'
```

| Field         | Type      | Description                                                                                                         |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `amount_atom` | `integer` | The **target** balance in the smallest currency unit (e.g. cents). A positive value is credit owed to the customer. |
| `currency`    | `string`  | Currency code (e.g. `USD`). Each currency's balance is independent.                                                 |

The response is the resulting balance:

```json
{ "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.

```bash
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"
}'
```

| Field         | Type      | Description                                                                                                                |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `amount_atom` | `integer` | Credit amount in the smallest currency unit. Must be greater than `0`.                                                     |
| `currency`    | `string`  | Currency code (e.g. `USD`).                                                                                                |
| `reason`      | `string`  | One of `proration_excess`, `manual_adjustment`, `auto_apply`, `debit_settlement`.                                          |
| `memo`        | `string`  | Optional human-readable note (max 500 chars).                                                                              |
| `invoice_id`  | `string`  | Optionally 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

```json
{
  "id": "cn_live_1a2b3c4d5e6f7g8h",
  "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"
}
```

| Field         | Description                                                                          |
| ------------- | ------------------------------------------------------------------------------------ |
| `id`          | Credit note identifier, prefixed `cn_`.                                              |
| `type`        | `issued` (credit added), `applied` (consumed by an invoice), or `voided` (reversed). |
| `amount_atom` | Positive when credit is issued; negative when applied or voided.                     |
| `invoice_id`  | The invoice the note is linked to, if any.                                           |

# List a customer's credit notes

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

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

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

| Event              | Trigger                                           |
| ------------------ | ------------------------------------------------- |
| `customer.updated` | A 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.