# Credit notes

A credit note is a booked accounting document, like an
[invoice](/guides/billing-documents/invoices), 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](/guides/billing-documents/overview).

## 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](/guides/billing-documents/overview#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](/guides/billing-documents/overview#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](/guides/billing-documents/invoices#send).
- `GET /v1/credit-notes/{id}/delivery-status` — same summary + per-attempt log as
  the [invoice delivery status](/guides/billing-documents/invoices#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](/guides/webhooks) covers endpoint setup, the signed-envelope format,
and the full topic list.