Credit Notes API

What this does

The Credit Notes API lets you manage refunds and adjustments programmatically: create credit notes, retrieve them individually or as a list, update their workflow status, and void them — which posts a reversing journal entry against the original GL posting.

When to use it

Use this endpoint when you need to issue a refund or sales adjustment against a customer — for example, returning goods, correcting an over-charge, or any reversal of an existing invoice.

Authentication and scopes

Requests must include Authorization: Bearer rly_your_key_here. Each endpoint requires one of:

• credit-notes:read — list and retrieve credit notes
• credit-notes:write — create, update status, and void credit notes

Endpoints

List credit notes

GET /api/v1/credit-notes

Returns a paginated list of credit notes. Supports ?page=1&limit=50 query parameters.

Create a credit note

POST /api/v1/credit-notes

{
  "customerId": "cust_abc123",
  "invoiceId": "inv_xyz789",
  "clientName": "Acme Ltd",
  "clientEmail": "[email protected]",
  "issueDate": "2026-04-25",
  "currency": "GBP",
  "reason": "Returned faulty unit",
  "notes": "Refund of 1 × widget",
  "items": [
    {
      "description": "Widget — refund",
      "quantity": 1,
      "unitPrice": 100.00,
      "taxRate": 20
    }
  ]
}

clientName and at least one items entry are required. customerId, invoiceId, clientEmail, issueDate, currency, reason, and notes are optional. VAT is applied per line item.

Response (201 Created): the created credit note object including id, credit_note_number, status: "draft", and totals. Posts a journal entry: Dr Sales / Dr VAT Output / Cr Debtors (the reverse of an invoice).

Get a single credit note

GET /api/v1/credit-notes/:id

Returns the credit note with its items array.

Update credit note status

PATCH /api/v1/credit-notes/:id

{ "status": "issued" }

Allowed values for status: draft, issued, applied. To void, use the action field below — voiding posts a reversing GL entry, so it can't be done via plain status update.

Void a credit note

PATCH /api/v1/credit-notes/:id

{ "action": "void" }

Voids the credit note and posts a reversing journal entry against the original GL posting. The credit note's status becomes voided.

• 404 not_found — credit note does not exist
• 409 conflict — credit note is already voided
• 403 period_locked (on create) — issue date falls in a locked period

Test mode

Keys flagged as test mode validate request bodies but skip database writes. The response includes "test": true and a stubbed id / credit_note_number so you can exercise the integration safely.