Credit notes

A credit note is a booked accounting document, like an invoice, and shares the same scope pair (invoices-read / invoices-write). It differs in two ways: it is numbered on creation (an invoice is numbered on send), and its totals are negative. The shared line model, reads, and send channels are in Billing documents.

Create a credit note

POST /v1/credit-notes returns the credit note as PublicCreditNote. customerId is required. Pass the optional invoiceNumber to credit an existing invoice; the referenced invoice is then marked credited. A credit note is numbered on creation.

Lines follow the same rules as an invoice (see Document lines): send priceId + quantity, with an optional positive unitPrice override. The credit (negative) sign is applied server-side — a line that derives 300.00 from its price is recorded as -300.00 on the credit note, so the totals are negative.

Status values

Credit note status is one of draft, scheduled, sending, sent.

List, get, download, send, and track

These work identically to invoices — swap /invoices/ for /credit-notes/ in the path:

• GET /v1/credit-notes and GET /v1/credit-notes/{id} — see Reading documents.
• GET /v1/credit-notes/{id}/pdf (?draft=true for a preview).
• POST /v1/credit-notes/{id}/send — same channels and recipient fields as the invoice send.
• GET /v1/credit-notes/{id}/delivery-status — same summary + per-attempt log as the invoice delivery status.

Webhook events

Subscription-driven credit notes (those the billing engine sends) emit the billing.credit_note_sent topic. Credit notes you create and send directly over this API are booked the same way but are not subscription events. Webhooks covers endpoint setup, the signed-envelope format, and the full topic list.