Copy page

Billing documents

Credit notes

A credit note is a booked accounting document, like an invoice, and shares the same scope pair (invoices-read / invoices-write). Like an invoice, it is numbered when it is sent: number is null until then, and sending draws the next number of the company's credit note series. Unlike an invoice, 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 response is a draft with number: null. The referenced invoice is marked credited once the credit notes sent against it give back its whole amount before VAT. Each credit note counts for its net: a charge line on it, such as a restocking fee, reduces what it gives back.

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.

A credit note that names no invoice takes discount ids like an invoice does (see Discounts); the amounts each discount took off are reported as positive figures. A credit note that names invoiceNumber takes no discounts of its own: sending discountIds with invoiceNumber is refused with DISCOUNT_CREDIT_NOTE_FOLLOWS_INVOICE. Instead, each line can name the invoice line it credits, and then gives back the discounts that invoice line used.

Credit specific invoice lines

To credit part of an invoice, send invoiceNumber and set sourceInvoiceLineId on each line to the id of the invoice line it credits (from lines[].id on GET /v1/invoices/{id}):

Code
{
  "customerId": "0197A943-2325-7829-B835-B6C71A293065",
  "invoiceNumber": "INV-1042",
  "date": "2026-01-15",
  "lines": [
    {
      "priceId": "0197A943-2325-7829-B835-B6C71A293066",
      "quantity": 2,
      "sourceInvoiceLineId": "0197A943-2325-7829-B835-B6C71A293067"
    }
  ]
}

A linked line gives back the line discounts the invoice line was billed with and its share of the invoice's document discounts, and reports them in appliedDiscounts and totalDiscounted. A line without sourceInvoiceLineId gives back no discounts. Each line of the returned credit note carries the sourceInvoiceLineId it was sent with, or null on a line sent without one. The amount you credit is not checked against what remains on the invoice line: a linked line, like an unlinked one, can credit more than the invoice line has left.

Code	Cause
CREDIT_NOTE_SOURCE_LINE_NOT_ON_INVOICE	sourceInvoiceLineId names a line that is not on the invoice invoiceNumber names, or is sent without invoiceNumber.
DISCOUNT_CREDIT_NOTE_FOLLOWS_INVOICE	discountIds sent on a credit note that names invoiceNumber.

To credit every line, use Credit a whole invoice.

Credit a whole invoice

POST /v1/credit-notes/from-invoice/{invoiceId} reverses every line of an invoice and returns the resulting draft as PublicCreditNote. Send no body.

Code
POST /v1/credit-notes/from-invoice/0197A943-2325-7829-B835-B6C71A293065

Use it whenever you credit an invoice in full. Each credit line carries the VAT rate the invoice charged rather than the current catalog rate, inherits the original line's dimensions, and is linked to the invoice line it reverses. That linkage is what marks the invoice credited once you send the credit note.

The result is a draft, so nothing is booked until you send it. An invoice that is still a draft, already credited, has no invoice number, or carries no lines returns 400 — the last because a credit with nothing to reverse would be a sendable document crediting nothing.

Status values

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

Payer identity

A credit note the billing engine issues for one subscription carries customerSubscriptionId. One issued for a billing group carries billingGroupId instead, never both. A group's credit notes render as one flat document; the id is a payer identity, not a document shape. A credit note you create carries neither.

Each line names the subscription it credits in subscriptionId, and an add-on's lines name its parent in addonOfSubscriptionId — the same two fields as on invoice lines. The subscriptionId list filter exists on GET /v1/invoices only; GET /v1/credit-notes does not take it.

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.

Credit notes need a number prefix, so that a credit note and an invoice never share a number. While your credit note series has no prefix, creating a credit note and sending a draft for the first time are refused, and the draft is left unchanged. Set a prefix in the numbering settings, then send it again. Sending a credit note that has already been sent is not affected.

Code	Cause
CREDIT_NOTE_PREFIX_REQUIRED	POST /v1/credit-notes, or the first POST /v1/credit-notes/{id}/send of a draft, while your credit note series has no prefix.

Webhook events

Subscription-driven credit notes (those the billing engine sends) emit the billing.credit_note_sent topic. For a group's credit note the payload's subscriptionId is null; read the credit note for its billingGroupId. 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.