Supplier Credit Notes

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.

All requests below require the x-dolfin-api-key and x-dolfin-organisation-id headers. See Authentication.

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

Create the credit note

POST /v1/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.

Issue it

POST /v1/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.

Apply it to a bill

POST /v1/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.

Reverse if needed

DELETE /v1/supplier-credit-notes/{id}/applications/{applicationId} un-credits the bill and returns the credit to the note’s available balance.

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.

curl -X POST https://api.dolfinai.co/v1/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"
  }'

const creditNote = await fetch(
  'https://api.dolfinai.co/v1/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());

Response (201 Created):

{
  "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"
}

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

Issue the credit note

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

curl -X POST https://api.dolfinai.co/v1/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.

curl -X POST https://api.dolfinai.co/v1/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
  }'

const application = await fetch(
  'https://api.dolfinai.co/v1/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());

Response (201 Created):

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

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

Reverse an application

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

curl -X DELETE https://api.dolfinai.co/v1/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

# A single credit note
curl https://api.dolfinai.co/v1/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/v1/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/v1/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/v1/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.

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

[
  { "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.

curl "https://api.dolfinai.co/v1/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. See the webhooks guide for setup, signature verification, and delivery behaviour.

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.

Getting started

Accounts Payable

Accounts Receivable

Supplier Credit Notes

Concepts

Lifecycle

Create a credit note

Issue the credit note

Apply credit to a bill

Reverse an application

Read endpoints

Supplier balance and ledger

Webhooks

Notes

Next steps

Quick Start - AP

Three-way Matching

​Concepts

​Lifecycle

​Create a credit note

​Issue the credit note

​Apply credit to a bill

​Reverse an application

​Read endpoints

​Supplier balance and ledger

​Webhooks

​Notes

​Next steps

Quick Start - AP

Three-way Matching

Concepts

Lifecycle

Create a credit note

Issue the credit note

Apply credit to a bill

Reverse an application

Read endpoints

Supplier balance and ledger

Webhooks

Notes

Next steps