API
Invoices API
Create invoices with per-line VAT, send or issue them, record offline payments or allocate existing payments, and cancel them.
On this page
- Overview
- The invoice object
- Statuses
- Payments on an invoice
- Create an invoice
- VAT and totals
- Billing periods and line details
- Idempotent creation
- Pay links
- List invoices
- Get an invoice
- Download the invoice PDF
- Send an invoice
- Issue an invoice without emailing
- Record an offline payment
- Allocate an existing payment
- Cancel an invoice
- Webhook events
- Errors
Overview#
Create invoices from your system, let CentraPoint email them with a secure pay link, and keep them up to date as money arrives, whether through a gateway or offline (EFT, cash). Requires a plan that includes Invoicing; pay links also need the Payment links feature.
| Endpoint | Purpose |
|---|---|
POST /api/v1/invoices | Create (idempotent on externalReference) |
GET /api/v1/invoices | List, filter by number, customer, reference, status or issue date (paginated) |
GET /api/v1/invoices/{id} | Get one invoice (by ID or invoice number), with its payments |
POST /api/v1/invoices/{id}/send | Email it with a pay link |
POST /api/v1/invoices/{id}/issue | Mark it issued (sent) without emailing |
POST /api/v1/invoices/{id}/payments | Record an offline payment, or allocate an existing payment |
POST /api/v1/invoices/{id}/cancel | Void an unpaid invoice |
Every {id} in these paths accepts the invoice's CentraPoint ID or its number (for example INV-000042), like quotes and refunds.
The invoice object#
{
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "sent",
"externalReference": "ORDER-1001",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"currency": "ZAR",
"issueDate": "2026-09-24T22:00:00.000Z",
"dueDate": "2026-10-08T21:59:59.000Z",
"periodStart": "2026-10-01",
"periodEnd": "2026-10-31",
"lines": [
{
"description": "Website hosting - October",
"details": "Business hosting plan\nDomain: nkosi.example.co.za",
"quantity": 1,
"unitPrice": 434.78,
"taxRate": 15,
"amount": 434.78,
"periodStart": null,
"periodEnd": null
},
{
"description": "Domain renewal (zero-rated)",
"details": null,
"quantity": 1,
"unitPrice": 120,
"taxRate": 0,
"amount": 120,
"periodStart": "2026-10-01",
"periodEnd": "2027-09-30"
}
],
"taxInclusive": false,
"subtotal": 554.78,
"taxAmount": 65.22,
"total": 620,
"amountPaid": 0,
"amountDue": 620,
"paidAt": null,
"payments": [],
"payUrl": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
"notes": "Payment due within 14 days.",
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:05:00.000Z",
"updatedAt": "2026-09-25T08:05:00.000Z"
}| Field | Type | Description |
|---|---|---|
idrequired | string | CentraPoint invoice ID. |
numberrequired | string | Sequential invoice number, e.g. INV-000042. |
statusrequired | string | See Statuses. |
externalReferencerequired | string | null | Your ID for the invoice. |
customerrequired | object | { id, externalReference, email } |
currencyrequired | string | ISO 4217 code. |
issueDate, dueDaterequired | string | ISO 8601 UTC timestamps (dates are interpreted in South African time). |
periodStart, periodEndrequired | string | null | Billing period the invoice covers (YYYY-MM-DD, inclusive), or null for once-off sales. See Billing periods. |
linesrequired | object[] | description, details (string | null), quantity, unitPrice, taxRate (%), amount, periodStart / periodEnd (YYYY-MM-DD | null, the line's own period). Prices and amounts exclude VAT, or include it when taxInclusive is true. |
taxInclusiverequired | boolean | true when the line prices include tax (worked out of each line); false when tax was added on top. subtotal is always excluding VAT. See VAT and totals. |
subtotal, taxAmount, totalrequired | number | Totals excluding VAT, VAT, and including VAT. |
amountPaid, amountDuerequired | number | Paid so far, and the outstanding balance. |
paidAtrequired | string | null | When the invoice was fully paid. |
paymentsrequired | object[] | Money received against the invoice, oldest first; see Payments on an invoice. |
payUrlrequired | string | null | Hosted payment page for the balance. See Pay links. |
notesrequired | string | null | Printed on the invoice. |
metadatarequired | object | Your key/value data (rules). |
createdAt, updatedAtrequired | string |
Statuses#
| status | Meaning |
|---|---|
draft | Created but not sent. Nothing paid. |
sent | Sent (or payable). Nothing paid. |
overdue | Past the due date. Nothing paid. Set by a daily job (01:00 South African time). |
partially_paid | Some money received, balance outstanding (reported instead of draft/sent/overdue). |
paid | Fully paid. |
cancelled | Voided. |
Payments on an invoice#
payments lists both kinds of money received: offline payments recorded with POST /payments (or in the dashboard, or imported), and completed CentraPoint payments linked to the invoice (pay link checkouts, debit orders, reconciled EFT, and payments allocated to it). It is included wherever the invoice object appears: get, list and invoice.* webhooks.
[
{
"id": "cmg2p1a2b0007txn0001abcd",
"source": "transaction",
"origin": "gateway",
"method": "payfast",
"status": "complete",
"amount": 300,
"refundedAmount": 0,
"currency": "ZAR",
"date": "2026-09-30T09:12:44.000Z",
"reference": "2281394",
"transactionReference": "CP-20260930-7K2M9QXA"
},
{
"id": "cmg2q8r4s0009ipay0001abcd",
"source": "offline",
"origin": "api",
"method": "eft",
"status": "complete",
"amount": 320,
"refundedAmount": 0,
"currency": "ZAR",
"date": "2026-10-02T08:15:00.000Z",
"reference": "FNB 2026-10-02 NKOSI",
"transactionReference": null
}
]| Field | Type | Description |
|---|---|---|
idrequired | string | The offline payment's ID, or the transaction's ID. |
sourcerequired | string | offline (recorded outside the gateways) or transaction (a CentraPoint payment, see Transactions). |
originrequired | string | Offline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway. |
methodrequired | string | Offline: eft, cash, card, wallet or other. Transactions: the gateway type, e.g. payfast, manual_eft, netcash_debit. |
statusrequired | string | Offline: always complete. Transactions: complete, partially_refunded or refunded. |
amount, refundedAmountrequired | number | Amount received and, for transactions, how much of it was refunded (refunds reduce the invoice's amountPaid). |
currencyrequired | string | ISO 4217 code. |
daterequired | string | When the money was received (ISO 8601). |
referencerequired | string | null | Offline: the payer's or bank reference you recorded. Transactions: the gateway's reference. |
transactionReferencerequired | string | null | Transactions: the CentraPoint reference (GET /api/v1/transactions/{reference}, receipts). Offline: null. |
Create an invoice#
/api/v1/invoices| Field | Type | Description |
|---|---|---|
customerIdoptional | string | The customer's CentraPoint ID. Send exactly one of customerId or customer. |
customeroptional | object | { "id": "…" } or { "externalReference": "…" } of an existing customer. Create customers first with the Customers API. Send exactly one of customerId or customer. |
linesrequired | object[] | 1–200 lines: description (1–1000 chars), quantity (> 0), unitPrice (≥ 0, excl. VAT), optional taxRate (0–100, default: your organisation's tax rate from Settings → Tax). unitPrice includes tax when taxInclusive is true. Optional details (up to 4000 chars) and periodStart / periodEnd; see Billing periods and line details. |
externalReferenceoptional | string | 1–190 chars. Makes creation idempotent; see below. |
currencyoptional | string | ISO 4217 code, default ZAR. Invalid codes are rejected with 400. No gateway is required (invoices can be paid offline), but payUrl is only created when a gateway accepts the currency. |
issueDateoptional | string (YYYY-MM-DD) | Default today. |
dueDateoptional | string (YYYY-MM-DD) | Default: today plus your invoice due-days setting. |
periodStart, periodEndoptional | string (YYYY-MM-DD) | Billing period the invoice covers, inclusive calendar dates. Send both or neither; periodEnd must be on or after periodStart. Omit for once-off sales. |
notesoptional | string | Up to 4000 chars. Default: your invoice terms (Settings → Company settings). |
taxInclusiveoptional | boolean | Default false: tax is added on top of the line prices. true: line prices already include tax, which is worked out of them. See VAT and totals. |
metadataoptional | object | Key/value data. |
statusoptional | string | draft (default) or sent. sent issues the invoice without emailing it (unless send is true), like POST /issue. draft cannot be combined with send or issue (400). |
issueoptional | boolean | Same as status: "sent": issue without emailing. |
sendoptional | boolean | Default false. true issues the invoice (sent) and emails it to the customer with the pay link. send: false with status: "sent" or issue: true issues it with no email. |
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 7d0c9b1e-2f4a-4c8e-b6d3-1a5e9f2c7b40" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"externalReference": "CRM-1001"
},
"externalReference": "ORDER-1001",
"dueDate": "2026-10-08",
"periodStart": "2026-10-01",
"periodEnd": "2026-10-31",
"lines": [
{
"description": "Website hosting - October",
"details": "Business hosting plan\nDomain: nkosi.example.co.za",
"quantity": 1,
"unitPrice": 434.78
},
{
"description": "Domain renewal (zero-rated)",
"quantity": 1,
"unitPrice": 120,
"taxRate": 0,
"periodStart": "2026-10-01",
"periodEnd": "2027-09-30"
}
],
"metadata": {
"crmId": "0061x00000AbCdE"
},
"send": true
}'Returns 201 with the invoice object.
VAT and totals#
- Each line's
amountis quantity × unit price, rounded to cents; VAT is calculated per line at its own rate. subtotalis the sum of line amounts,taxAmountthe sum of line VAT,totaltheir sum. The total must be greater than zero.- Use
taxRate: 0for zero-rated or exempt lines. - With
taxInclusive: true, each line'samountincludes tax and its tax isamount × rate / (100 + rate), rounded to cents;totalis the sum of the line amounts andsubtotalistotal − taxAmount. For example one line of 1 150.00 at 15% gives tax 150.00, subtotal 1 000.00 and total 1 150.00. - The API defaults to exclusive pricing regardless of the inclusive/exclusive setting under Settings → Tax (which applies to the dashboard and subscription billing), so send
taxInclusiveexplicitly if your prices include tax.
Billing periods and line details#
periodStart/periodEndon the invoice record the period it bills (YYYY-MM-DD, inclusive calendar dates). Send both or neither; aperiodEndbeforeperiodStartreturns400.- Each line can carry
details: a longer, multi-line description (up to 4000 chars) shown under the shortdescription, for example plan features, usage, a domain name or a reference. - A line can have its own
periodStart/periodEnd(same rules) when it differs from the invoice period, for example a prorated add-on or an annual renewal on a monthly invoice. - PDFs, emails and the customer portal show Billing period: 1 Oct 2026 - 31 Oct 2026 under the header, and each line's details under its description (plus the line period when it differs from the invoice's).
- Subscription invoices are filled in automatically: the period is the billing cycle, the line description is
<Package> - <Plan> (<Frequency>), and the details list the plan, cycle, period, quantity, features and any coupon. - Converting a quote copies its period and each line's details and period to the invoice.
Idempotent creation#
If an invoice with the same externalReference already exists, the request returns that invoice with 200 and changes nothing: the new body is ignored and send is not repeated. Use this to make retries safe, or combine it with an Idempotency-Key.
Pay links#
When your plan includes payment links and one of your gateways accepts the invoice currency, CentraPoint creates a single-use pay link for the outstanding balance and returns it as payUrl. The link carries the invoice's externalReference. If the balance changes (a part payment), the next send creates a fresh link for the new balance.payUrl is null for paid or cancelled invoices, and when no link could be created. If you have a Manual EFT gateway, the pay link also offers Bank transfer (EFT), and it can be created even when Manual EFT is your only gateway; approving the payer's EFT order pays the invoice (see EFT at hosted checkout).
List invoices#
/api/v1/invoices| Field | Type | Description |
|---|---|---|
numberoptional | string | Exact invoice number, e.g. INV-000042. |
statusoptional | string | One or more, comma-separated: draft, sent, overdue (these three only match invoices with nothing paid yet), partially_paid (open invoices with money received), paid or cancelled. For example status=sent,overdue,partially_paid for everything outstanding. |
customerIdoptional | string | Only this customer's invoices. |
customerExternalReferenceoptional | string | Only invoices of the customer with this reference. |
externalReferenceoptional | string | Exact match. |
from, tooptional | string (date) | Issue date range (YYYY-MM-DD, SAST, inclusive). |
limit, startingAfteroptional | Keyset pagination: the response is { data, hasMore, nextCursor }, newest first. |
startingAfter must be the id of an invoice in the same filtered list (normally the previous page's nextCursor), otherwise the request returns 400. Clients that only read data keep working: without startingAfter you get the newest limit invoices, as before.
curl -X GET "https://app.centrapoint.co.za/api/v1/invoices?status=sent,overdue,partially_paid&from=2026-09-01&limit=50" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get an invoice#
/api/v1/invoices/{id}{id} is the invoice ID or its number. Returns the invoice object, including payments, or 404.
curl -X GET "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"curl -X GET "https://app.centrapoint.co.za/api/v1/invoices/INV-000042" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Download the invoice PDF#
/api/v1/invoices/{id}/pdfReturns the branded invoice PDF (application/pdf, as an attachment, Cache-Control: private, no-store) or 404. Needs Invoicing in your plan. Receipts and refund notes are available from the Receipts & refunds API; see Tax & PDF documents.
curl -o invoice.pdf \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
"https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/pdf"Send an invoice#
/api/v1/invoices/{id}/sendEmails the invoice to the customer, including a pay link for the balance when possible. A draft becomes sent. No body is needed. Paid and cancelled invoices can't be sent (400). Returns the updated invoice. Sending always emails; to issue an invoice without an email use POST /issue.
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/send" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: b21e6f0a-5c3d-4e8f-9a7b-2c1d0e3f4a56"Issue an invoice without emailing#
/api/v1/invoices/{id}/issueMarks a draft as issued (sent) without emailing the customer, for platforms that deliver invoices themselves. The invoice becomes payable, reminders and the overdue job apply to it, it syncs to your accounting system, invoice.sent is sent, and a pay link is created (payUrl) when your plan and gateways allow. No body is needed. Invoices that are already issued (sent, overdue, partially_paid, paid) are returned unchanged with 200; cancelled invoices return 400. To issue at creation, send status: "sent" (or issue: true) to POST /api/v1/invoices.
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/INV-000042/issue" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 0f4b8d2a-6c1e-4a3f-9b5d-7e2c4a6f8b13"Record an offline payment#
/api/v1/invoices/{id}/paymentsRecords money received outside CentraPoint's gateways. Payments made through a pay link are recorded automatically; don't record them again.
| Field | Type | Description |
|---|---|---|
amountrequired | number | Greater than 0 and not more than the outstanding balance. |
methodrequired | string | eft, cash, card, wallet or other. |
referenceoptional | string | Up to 190 chars, e.g. the bank statement reference. |
paidAtoptional | string (date-time) | ISO 8601 with Z or an offset. Default now; cannot be in the future. |
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/payments" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: c4a8e2f6-1b3d-4f5a-8c7e-9d0b2a4c6e81" \
-H "Content-Type: application/json" \
-d '{
"amount": 620,
"method": "eft",
"reference": "FNB 2026-10-02 NKOSI",
"paidAt": "2026-10-02T10:15:00+02:00"
}'Returns 201 with the updated invoice: paid when fully paid (its pay links are deactivated), otherwise partially_paid.
Allocate an existing payment#
When the customer already paid through CentraPoint but the payment is not linked to the invoice (for example through a plain payment link or a reconciled EFT), allocate it instead of recording new money: send only transactionReference, the payment's CentraPoint reference (CP-…, as in Transactions and receipts).
| Field | Type | Description |
|---|---|---|
transactionReferencerequired | string | Reference (or ID) of a completed transaction of your organisation. Send it on its own: combining it with amount, method, reference or paidAt returns 400. |
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/INV-000042/payments" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 5a7c9e1b-3d5f-4b7a-8c9e-1f3a5c7e9b20" \
-H "Content-Type: application/json" \
-d '{
"transactionReference": "CP-20260930-7K2M9QXA"
}'- The transaction is linked to the invoice and its full amount is added to
amountPaid(the invoice becomespaidorpartially_paid, andinvoice.paid/invoice.partially_paidis sent). It then appears in payments withsource: "transaction", and in the transaction'sinvoice. - Returns
201with the invoice;200(unchanged) when the payment is already allocated to this invoice, so retries are safe. - Rejected with
409 already_allocatedwhen the payment belongs to another invoice, and with400when it is not complete or was (partly) refunded, is in another currency, belongs to another customer, would exceed the outstanding balance, or the invoice is paid or cancelled. - Accounting: a payment not yet synced is created against the invoice; one already synced keeps its existing entry in your accounting system.
Cancel an invoice#
/api/v1/invoices/{id}/cancelVoids an unpaid or partially paid invoice and deactivates its pay links. Optional body { "reason": "…" } (up to 500 chars) is added to the notes. Cancelling a cancelled invoice returns it unchanged. Paid invoices can't be cancelled (400); record a refund or credit instead. Money already received on a partially paid invoice is not refunded automatically.
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: e9f1a3c5-7b2d-4e6f-8a0c-3b5d7f9a1c24" \
-H "Content-Type: application/json" \
-d '{
"reason": "Order cancelled by customer"
}'Webhook events#
invoice.created, invoice.sent, invoice.paid, invoice.partially_paid and invoice.cancelled are sent to your webhook endpoints with the invoice object as data (the same object GET /api/v1/invoices/{id} returns), whether the invoice was made through the API, the dashboard, a quote conversion or subscription billing, and whether the money came through a gateway, was allocated or was recorded offline. invoice.sent is sent when an invoice is created issued (send: true, status: "sent" or issue: true) or a draft is sent or issued. Renewals of an invoice-linked recurring payment link create a new invoice each cycle (invoice.created, invoice.sent, then invoice.paid).
Errors#
| Status | error | When |
|---|---|---|
| 400 | invalid_request | Validation failed; invalid ISO 4217 currency; customer not found; total not above zero; only one of periodStart/periodEnd, or periodEnd before periodStart; status draft with send/issue; unknown status filter, date not YYYY-MM-DD or unknown startingAfter (list); invoice paid/cancelled (send, payments), cancelled (issue); amount above balance; paidAt in the future; allocated transaction not found, not complete, refunded, in another currency or of another customer. |
| 403 | plan_restricted / account_restricted | Plan lacks the API or Invoicing, or the account is read-only (writes). |
| 404 | not_found | No invoice with this ID or number in your organisation. |
| 409 | idempotency_conflict | Idempotency-Key reused with a different body. |
| 409 | already_allocated | Allocation: the transaction is already allocated to another invoice. |
| 401 / 429 / 500 | unauthorized / rate_limited / internal_error | See Errors |