> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Supplier Credit Notes

> Record credit a supplier owes you, net it against bills, and reconcile from a derived balance and ledger

A **supplier credit note** records value a supplier owes the organisation — faulty goods, an
overcharge, a returned order. It is a **positive** document scoped to a supplier. You **issue**
it to make the credit available, then **apply** it to one or more bills you owe that supplier.
Applying nets the credit against the bill, reducing what's left to pay (the bill's
`outstanding`).

A bill reaches a zero balance only by having credit applied — **bills themselves are never
negative**. Every application is **reversible**, returning the credit to the note.

<Note>
  All requests below require the `x-dolfin-api-key` and `x-dolfin-organisation-id` headers. See
  [Authentication](/guides/authentication).
</Note>

## Concepts

| Object                   | What it is                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| **Supplier credit note** | A positive, tax-inclusive credit a supplier owes you, scoped to that supplier and a currency.           |
| **Available**            | The credit left to apply (`Amount − AppliedAmount`). Drawn down by applications, restored by reversals. |
| **Application**          | One row netting part of a credit note against a single bill. Reversible.                                |
| **Balance**              | Derived, per-currency available credit for a supplier — never blended across currencies.                |
| **Ledger**               | The derived statement of movements (issuances `+`, applications `−`) that built the balance.            |

## Lifecycle

A supplier credit note moves through these statuses:

```
Draft → Issued → PartiallyApplied → Applied
```

<Steps>
  <Step title="Create the credit note">
    `POST /suppliers/{supplierId}/credit-notes` records the credit in `Draft`. The amount is the
    gross (tax-inclusive) credit; the net/tax split is computed server-side from `taxRateId`.
  </Step>

  <Step title="Issue it">
    `POST /supplier-credit-notes/{id}/issue` makes the credit **available** against the supplier.
    No bill is touched, and the note becomes immutable. A `Draft` note can be deleted instead.
  </Step>

  <Step title="Apply it to a bill">
    `POST /supplier-credit-notes/{id}/applications` nets credit against a bill you owe the same
    supplier, reducing the bill's `outstanding` and drawing down the note's `available` balance.
    The note moves to `PartiallyApplied`, then `Applied` once fully drawn down.
  </Step>

  <Step title="Reverse if needed">
    `DELETE /supplier-credit-notes/{id}/applications/{applicationId}` un-credits the bill and
    returns the credit to the note's available balance.
  </Step>
</Steps>

## Create a credit note

The amount is the **gross** (tax-inclusive) credit and must be positive. Pass an optional
`taxRateId` to split out tax (omit it for a zero-rated credit), and an optional `originalBillId`
as header-level provenance for the bill the credit relates to.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dolfinai.co/suppliers/a1b2c3d4-0000-0000-0000-000000000001/credit-notes \
    -H "x-dolfin-api-key: dol_live_abc123" \
    -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
    -H "content-type: application/json" \
    -d '{
      "amount": 120.00,
      "currency": "GBP",
      "taxRateId": "f0f0f0f0-0000-0000-0000-000000000020",
      "reason": "Faulty widgets returned"
    }'
  ```

  ```javascript Node.js theme={null}
  const creditNote = await fetch(
    'https://api.dolfinai.co/suppliers/a1b2c3d4-0000-0000-0000-000000000001/credit-notes',
    {
      method: 'POST',
      headers: {
        'x-dolfin-api-key': 'dol_live_abc123',
        'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        amount: 120.0,
        currency: 'GBP',
        taxRateId: 'f0f0f0f0-0000-0000-0000-000000000020',
        reason: 'Faulty widgets returned',
      }),
    },
  ).then(r => r.json());
  ```
</CodeGroup>

**Response (`201 Created`):**

```json theme={null}
{
  "id": "c0ffee00-0000-0000-0000-000000000001",
  "supplierId": "a1b2c3d4-0000-0000-0000-000000000001",
  "amount": 120.00,
  "netAmount": 100.00,
  "taxAmount": 20.00,
  "appliedAmount": 0.00,
  "available": 120.00,
  "currency": "GBP",
  "reason": "Faulty widgets returned",
  "status": "Draft",
  "issuedAt": null,
  "createdAt": "2026-06-30T09:00:00Z"
}
```

<Note>
  While the note is in `Draft` you can delete it with `DELETE /supplier-credit-notes/{id}`.
  Issued or applied notes cannot be deleted — reverse their applications instead.
</Note>

## Issue the credit note

Issuing makes the credit available against the supplier and freezes the note.

```bash theme={null}
curl -X POST https://api.dolfinai.co/supplier-credit-notes/c0ffee00-0000-0000-0000-000000000001/issue \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"
```

The note returns with `status: "Issued"` and an `issuedAt` timestamp. This is when the
`supplier_credit_note.issued` webhook fires.

## Apply credit to a bill

Net (part of) the available credit against a bill you owe the same supplier. The body carries
the `billId` and the `amount` to apply.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dolfinai.co/supplier-credit-notes/c0ffee00-0000-0000-0000-000000000001/applications \
    -H "x-dolfin-api-key: dol_live_abc123" \
    -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
    -H "content-type: application/json" \
    -d '{
      "billId": "b1234567-abcd-ef01-2345-6789abcdef01",
      "amount": 120.00
    }'
  ```

  ```javascript Node.js theme={null}
  const application = await fetch(
    'https://api.dolfinai.co/supplier-credit-notes/c0ffee00-0000-0000-0000-000000000001/applications',
    {
      method: 'POST',
      headers: {
        'x-dolfin-api-key': 'dol_live_abc123',
        'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        billId: 'b1234567-abcd-ef01-2345-6789abcdef01',
        amount: 120.0,
      }),
    },
  ).then(r => r.json());
  ```
</CodeGroup>

**Response (`201 Created`):**

```json theme={null}
{
  "id": "a99a99a9-0000-0000-0000-000000000001",
  "supplierCreditNoteId": "c0ffee00-0000-0000-0000-000000000001",
  "billId": "b1234567-abcd-ef01-2345-6789abcdef01",
  "supplierId": "a1b2c3d4-0000-0000-0000-000000000001",
  "amount": 120.00,
  "currency": "GBP",
  "status": "Applied",
  "createdAt": "2026-06-30T09:05:00Z"
}
```

The bill's `outstanding` drops by the applied amount, the note's `available` drops to match, and
both the `supplier_credit.applied` and `bill.credited` webhooks fire.

<Warning>
  An application is rejected when any of these guards fail:

  * **Amount** must be greater than zero, within the note's **available** balance
    (`SupplierCreditNote.ExceedsAvailable`), and within the bill's **outstanding** balance
    (`SupplierCreditNote.ExceedsBillOutstanding`).
  * The bill must belong to the **same supplier** (`SupplierCreditNote.SupplierMismatch`) and be
    in the **same currency** (`SupplierCreditNote.CurrencyMismatch`) as the credit note.
  * The bill must be in an **owed** (unpaid, not-yet-paid) state
    (`SupplierCreditNote.BillNotCreditable`).
  * The credit note must already be **issued** (`SupplierCreditNote.NotIssued`).
</Warning>

## Reverse an application

Reversing un-credits the bill (restoring its `outstanding`) and returns the credit to the note's
available balance.

```bash theme={null}
curl -X DELETE https://api.dolfinai.co/supplier-credit-notes/c0ffee00-0000-0000-0000-000000000001/applications/a99a99a9-0000-0000-0000-000000000001 \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"
```

Returns `204 No Content`. A reversal is blocked if the bill is no longer reversible
(`SupplierCreditNote.BillNotReversible`).

## Read endpoints

```bash theme={null}
# A single credit note
curl https://api.dolfinai.co/supplier-credit-notes/{id} \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"

# All of the organisation's credit notes (newest first; filter by supplierId, currency, status)
curl "https://api.dolfinai.co/supplier-credit-notes?supplierId={id}&status=Issued" \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"

# The bills a credit note has been netted against
curl https://api.dolfinai.co/supplier-credit-notes/{id}/applications \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"

# The credit notes netted against a bill (reverse lookup)
curl https://api.dolfinai.co/bills/{billId}/credit-applications \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"
```

### Supplier balance and ledger

A supplier's **available balance** is derived per currency from its issued and partially-applied
credit notes — it is never blended across currencies.

```bash theme={null}
# Available credit per currency for a supplier
curl https://api.dolfinai.co/suppliers/{supplierId}/credit \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"
```

```json theme={null}
[
  { "currency": "GBP", "available": 120.00 }
]
```

The **ledger** lists every movement that built that balance — credit notes issued (`+`) and
applications to bills (`−`) — newest first, with cursor-based pagination.

```bash theme={null}
curl "https://api.dolfinai.co/suppliers/{supplierId}/credit/ledger?limit=20" \
  -H "x-dolfin-api-key: $DOLFIN_API_KEY" -H "x-dolfin-organisation-id: $ORG_ID"
```

Each entry carries an `entryType` (`CreditNoteIssued`, `AppliedToBill`, or `ApplicationReversed`),
a signed `amount`, the `currency`, and `occurredAt`. Application entries also carry `billId` and
`applicationId`.

## Webhooks

Subscribe to supplier-credit lifecycle changes like any other Dolfin webhook:

| Event                         | When                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `supplier_credit_note.issued` | a credit note is issued and its credit becomes available                                  |
| `supplier_credit.applied`     | credit is netted against a bill                                                           |
| `bill.credited`               | fired against the underlying bill (with its reduced `outstanding`) when credit is applied |

The `supplier_credit.applied` payload carries the credit note plus the `billId`, `amount`, and
`currency` of the application; `bill.credited` reuses the standard bill payload so subscribers
get the full, now-credited bill.

## Notes

* Supplier credit notes are always **positive**, and bills never go negative — a credit only ever
  reduces a bill's `outstanding` toward zero.
* Amounts are **gross** (tax-inclusive); the net/tax split is computed server-side from
  `taxRateId`. Omit it for a zero-rated credit.
* OCR auto-detection of supplier credit notes is coming later; for now, create them explicitly
  via the API.

## Next steps

<CardGroup cols={2}>
  <Card title="Quick Start - AP" icon="rocket" href="/guides/quick-start-ap">
    Upload, review, and approve a bill before crediting it.
  </Card>

  <Card title="Three-way Matching" icon="code" href="/guides/three-way-matching">
    Match purchase orders to bills and gate approval on variances.
  </Card>
</CardGroup>