Credit Notes API

What a credit note does to the books: it adds a credit_note row to the client's payment ledger and settles the invoice by up to what the invoice still owes. Anything beyond that (for example when the invoice was already paid) stays on the client's account as credit, to be used on a later invoice or paid back and recorded as a refund. When credit notes cover the whole invoice its status becomes credited.

POST /invoice/:id/credit_note

Issues a credit note against an invoice that has been sent. Draft, scheduled, cancelled and fully credited invoices cannot be credited.

curl -X POST https://api.rebill.co.za/invoice/abc123/credit_note \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Event cancelled by the client",
    "full": true,
    "send_email": true
  }'

To credit only part of an invoice, leave full out and list the lines:

curl -X POST https://api.rebill.co.za/invoice/abc123/credit_note \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Two hours were not worked",
    "credit_date": "2026-10-27",
    "items": [
      {
        "type": "service",
        "name": "Consulting",
        "quantity": 2,
        "unit_price": 100000,
        "vat_type": "standard",
        "vat_rate": 1500
      }
    ]
  }'

Response (201 Created):

{
  "credit_note": {
    "id": "cn_001",
    "number": "CN-0001",
    "status": "issued",
    "invoice_id": "abc123",
    "invoice_number": "INV0001",
    "currency": "ZAR",
    "credit_date": "2026-10-27T00:00:00Z",
    "reason": "Two hours were not worked",
    "amount": 230000,
    "items": [...],
    "totals": {...}
  },
  "invoice": {
    "id": "abc123",
    "status": "paid",
    "amount": 575000,
    "amount_due": 0,
    "credited_amount": 230000,
    "credit_applied_amount": 0
  },
  "leftover_credit": 230000
}

A credit note can never reverse more than the invoice charged. The total credited across all credit notes cannot exceed the invoice total. For each VAT type and rate, the credit notes together cannot take more than the invoice charged at that rate, in value, in the amount excl. VAT, or in VAT: a credit note never reverses more VAT than the invoice charged at each rate. Each partial credit note rounds its own VAT, so lines credited one at a time drift from the invoice by a few cents. Two cases make a partial credit note credit exactly what is left at a rate instead. First, its lines at that rate take every invoice line still open there, in full quantity and at the invoice price (lines are matched by item_id, else by name, and together must be worth at least open_lines_value less a cent per open line, before the document discount and VAT included), and its value is within close_tolerance_all_lines cents of what is left: crediting the last lines at a rate always closes it. That allowance is a few cents, larger only on invoices with a fixed discount: that discount reaches each partial credit note as a rounded percentage, and the allowance grows by exactly the difference this makes at that rate, plus a cent. Second, for any other lines, its value is within close_tolerance cents of what is left, at most 5 cents, so a typed amount is never moved by more than that. Its lines at that rate then become one line (keeping the line's name when there was one, else "Balance of invoice #N") with the amount excl. VAT and the vat_amount left. Both figures are in List credit notes for an invoice. full: true credits everything left exactly, value and VAT, and always passes these limits. If the invoice has a document discount, a first full credit note copies it, and a partial credit note applies it as an effective percentage, so a line credited at full price is credited at what the client actually paid for it.

A refused issue returns 422 Unprocessable with a message:

The invoice's credited_amount grows by the credit note amount, and credit_applied_amount grows by the part the invoice absorbed (up to its amount_due at the time). The status is derived again:

Cash paid on an invoice is amount - amount_due - credit_applied_amount. A credit note is never counted as a payment received.

An invoice with a credit note cannot be cancelled, has its amounts, lines, number, client and date locked, stops accruing late fees, and its payments cannot be removed. Credit the remaining balance instead.

GET /invoice/:id/credit_note

Returns the credit notes issued against one invoice, plus what is still left to credit. Use it to prefill a form for the next partial credit note.

curl https://api.rebill.co.za/invoice/abc123/credit_note \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "credit_notes": [...],
  "remaining": 345000,
  "remaining_by_group": [
    {
      "vat_type": "standard",
      "vat_rate": 1500,
      "remaining": 345000,
      "remaining_base": 300000,
      "remaining_vat": 45000,
      "close_tolerance": 1,
      "close_tolerance_all_lines": 2,
      "open_lines": [
        { "name": "Consulting", "quantity": 3 }
      ],
      "open_lines_value": 345000
    }
  ],
  "remainder_lines": [...],
  "partial_discount": { "type": "", "value": 0 }
}

GET /credit_note

Returns your credit notes, oldest credit date first.

curl "https://api.rebill.co.za/credit_note?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "credit_notes": [...]
}

GET /credit_note/:id

Returns one credit note object.

curl https://api.rebill.co.za/credit_note/cn_001 \
  -H "Authorization: Bearer sk_your_secret_key"

GET /credit_note/:id/pdf

Returns the credit note as a PDF, using your invoice template, logo and colours. The document is titled TAX CREDIT NOTE when your account has a VAT number, otherwise CREDIT NOTE. It shows the credit note number and date, your details and the client's, the credited lines with VAT, the reason, and the invoice it refers to. It has no bank details, payment link or due date, because a credit note asks for no payment.

curl https://api.rebill.co.za/credit_note/cn_001/pdf \
  -H "Authorization: Bearer sk_your_secret_key" \
  -o CreditNote-CN-0001.pdf

POST /credit_note/:id/send_email

Emails the credit note to the client, with a link to the online copy and, if your account attaches PDFs to emails, the PDF. Call it again to resend. Returns 422 Unprocessable with "Client has no email address" when the client has no email. Every send is recorded in the delivery log.

curl -X POST https://api.rebill.co.za/credit_note/cn_001/send_email \
  -H "Authorization: Bearer sk_your_secret_key"

GET /credit_note/:id/notification

Returns the delivery history of the emails sent for this credit note, in the same notifications and delivery shape as invoice notifications.

GET /p/cn/:public_id
GET /p/cn/:public_id/pdf

The unauthenticated endpoints behind the link in the credit note email. They take the credit note's public_id, return a limited view with no internal IDs, and need no API key. If the client has a document password, add ?pw= with that password; without it the response is 401.

Issuing a credit note emits credit_note.issued (resource ID: the credit note) and invoice.updated. When the invoice reaches credited it also emits invoice.credited, and when the credit note settles the last cents of an invoice it emits invoice.paid. A credit note is not money received, so it never emits payment.received or invoice.payment_received. See Webhooks.