Skip to main content
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

ObjectWhat it is
Supplier credit noteA positive, tax-inclusive credit a supplier owes you, scoped to that supplier and a currency.
AvailableThe credit left to apply (Amount − AppliedAmount). Drawn down by applications, restored by reversals.
ApplicationOne row netting part of a credit note against a single bill. Reversible.
BalanceDerived, per-currency available credit for a supplier — never blended across currencies.
LedgerThe derived statement of movements (issuances +, applications −) that built the balance.

​
Lifecycle

A supplier credit note moves through these statuses: 
Draft → Issued → PartiallyApplied → Applied
1

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

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

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

Reverse if needed

DELETE /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/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"
  }'
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 /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/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/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
  }'
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/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/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. 
# 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"

[
  { "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/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:
EventWhen
supplier_credit_note.issueda credit note is issued and its credit becomes available
supplier_credit.appliedcredit is netted against a bill
bill.creditedfired 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

Quick Start - AP

Upload, review, and approve a bill before crediting it.

Three-way Matching

Match purchase orders to bills and gate approval on variances.