Developer API

Billing and invoices API

The invoice lifecycle through the API, then the endpoints to list, create and void invoices and to list and create credit notes and debit notes, with their errors.

Updated 20 September 2026

The billing endpoints let an external system record sales, read the state of invoices, void an invoice and raise credit or debit notes, with the same records and numbering the counter uses. They sit under /api/v1/external/billing and need the headers described under Authentication; every POST and PATCH is signed.

Invoice states

An invoice created through the API starts as DRAFT. It becomes APPROVED when it is finalised or a payment is submitted, and PAID when the full payment is received. A draft or an approved invoice can be voided, which ends it as VOIDED. A paid invoice is corrected with a credit note, not a void; that keeps the original traceable, which is what the VAT register needs.

List invoices

GET /api/v1/external/billing/invoices

Optional page, limit and status (DRAFT, APPROVED, PAID or VOIDED).

{
  "success": true,
  "data": [
    {
      "id": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "billNumber": "INV-2082-0001",
      "totalAmount": 45000,
      "status": "APPROVED"
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 10 }
}

A date range where fromDate is after toDate is answered with 400.

Create an invoice

POST /api/v1/external/billing/invoices

{
  "customerId": "c1010101-2020-3030-4040-505050505050",
  "paymentMethod": "CASH",
  "items": [
    { "productId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "quantity": 2, "unitPrice": 1500 }
  ]
}

The response is 201 with the invoice’s id, its billNumber, status of DRAFT and totalAmount. An invalid line is answered with 400 and the row that failed; an unknown customer with 404 Customer not found.

Void an invoice

PATCH /api/v1/external/billing/invoices/:id/void

id is the invoice UUID. Give the reason in the body:

{ "reason": "Customer returned purchased items" }

The response returns the invoice with status of VOIDED. Voiding an invoice that is already void is answered with 409 Invoice is already voided; an id that is not a valid UUID with 400.

Credit notes

GET /api/v1/external/billing/credit-notes
POST /api/v1/external/billing/credit-notes

The list is paginated and returns each note’s id, creditNoteNumber, amount and status. To create one, send the invoice it applies to, the amount and the reason:

{
  "invoiceId": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "amount": 5000,
  "reason": "Price correction credit"
}

The response is 201 with the note as DRAFT. An amount larger than the invoice balance is answered with 400 Credit note amount exceeds invoice balance.

Debit notes

GET /api/v1/external/billing/debit-notes
POST /api/v1/external/billing/debit-notes

Same shape as credit notes, with debitNoteNumber:

{
  "invoiceId": "e5f67a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "amount": 4200,
  "reason": "Additional delivery charge adjustment"
}

An unknown invoice is answered with 404 Referenced invoice not found.

Click-by-click steps in the help centre What this feature does