CentraPoint

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#

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.

Invoice endpoints
EndpointPurpose
POST /api/v1/invoicesCreate (idempotent on externalReference)
GET /api/v1/invoicesList, 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}/sendEmail it with a pay link
POST /api/v1/invoices/{id}/issueMark it issued (sent) without emailing
POST /api/v1/invoices/{id}/paymentsRecord an offline payment, or allocate an existing payment
POST /api/v1/invoices/{id}/cancelVoid 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#

Invoice
{
  "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"
}
Invoice fields
FieldTypeDescription
idrequiredstringCentraPoint invoice ID.
numberrequiredstringSequential invoice number, e.g. INV-000042.
statusrequiredstringSee Statuses.
externalReferencerequiredstring | nullYour ID for the invoice.
customerrequiredobject{ id, externalReference, email }
currencyrequiredstringISO 4217 code.
issueDate, dueDaterequiredstringISO 8601 UTC timestamps (dates are interpreted in South African time).
periodStart, periodEndrequiredstring | nullBilling period the invoice covers (YYYY-MM-DD, inclusive), or null for once-off sales. See Billing periods.
linesrequiredobject[]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.
taxInclusiverequiredbooleantrue 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, totalrequirednumberTotals excluding VAT, VAT, and including VAT.
amountPaid, amountDuerequirednumberPaid so far, and the outstanding balance.
paidAtrequiredstring | nullWhen the invoice was fully paid.
paymentsrequiredobject[]Money received against the invoice, oldest first; see Payments on an invoice.
payUrlrequiredstring | nullHosted payment page for the balance. See Pay links.
notesrequiredstring | nullPrinted on the invoice.
metadatarequiredobjectYour key/value data (rules).
createdAt, updatedAtrequiredstring

Statuses#

Invoice statuses
statusMeaning
draftCreated but not sent. Nothing paid.
sentSent (or payable). Nothing paid.
overduePast the due date. Nothing paid. Set by a daily job (01:00 South African time).
partially_paidSome money received, balance outstanding (reported instead of draft/sent/overdue).
paidFully paid.
cancelledVoided.

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.

payments
[
  {
    "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
  }
]
Payment entry fields
FieldTypeDescription
idrequiredstringThe offline payment's ID, or the transaction's ID.
sourcerequiredstringoffline (recorded outside the gateways) or transaction (a CentraPoint payment, see Transactions).
originrequiredstringOffline: api, dashboard or accounting (imported from an accounting system). Transactions: gateway.
methodrequiredstringOffline: eft, cash, card, wallet or other. Transactions: the gateway type, e.g. payfast, manual_eft, netcash_debit.
statusrequiredstringOffline: always complete. Transactions: complete, partially_refunded or refunded.
amount, refundedAmountrequirednumberAmount received and, for transactions, how much of it was refunded (refunds reduce the invoice's amountPaid).
currencyrequiredstringISO 4217 code.
daterequiredstringWhen the money was received (ISO 8601).
referencerequiredstring | nullOffline: the payer's or bank reference you recorded. Transactions: the gateway's reference.
transactionReferencerequiredstring | nullTransactions: the CentraPoint reference (GET /api/v1/transactions/{reference}, receipts). Offline: null.

Create an invoice#

POST/api/v1/invoices
Create invoice fields
FieldTypeDescription
customerIdoptionalstringThe customer's CentraPoint ID. Send exactly one of customerId or customer.
customeroptionalobject{ "id": "…" } or { "externalReference": "…" } of an existing customer. Create customers first with the Customers API. Send exactly one of customerId or customer.
linesrequiredobject[]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.
externalReferenceoptionalstring1–190 chars. Makes creation idempotent; see below.
currencyoptionalstringISO 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.
issueDateoptionalstring (YYYY-MM-DD)Default today.
dueDateoptionalstring (YYYY-MM-DD)Default: today plus your invoice due-days setting.
periodStart, periodEndoptionalstring (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.
notesoptionalstringUp to 4000 chars. Default: your invoice terms (Settings → Company settings).
taxInclusiveoptionalbooleanDefault 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.
metadataoptionalobjectKey/value data.
statusoptionalstringdraft (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).
issueoptionalbooleanSame as status: "sent": issue without emailing.
sendoptionalbooleanDefault 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 amount is quantity × unit price, rounded to cents; VAT is calculated per line at its own rate.
  • subtotal is the sum of line amounts, taxAmount the sum of line VAT, total their sum. The total must be greater than zero.
  • Use taxRate: 0 for zero-rated or exempt lines.
  • With taxInclusive: true, each line's amount includes tax and its tax is amount × rate / (100 + rate), rounded to cents; total is the sum of the line amounts and subtotal is total − 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 taxInclusive explicitly if your prices include tax.

Billing periods and line details#

  • periodStart / periodEnd on the invoice record the period it bills (YYYY-MM-DD, inclusive calendar dates). Send both or neither; a periodEnd before periodStart returns 400.
  • Each line can carry details: a longer, multi-line description (up to 4000 chars) shown under the short description, 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.

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#

GET/api/v1/invoices
List query parameters
FieldTypeDescription
numberoptionalstringExact invoice number, e.g. INV-000042.
statusoptionalstringOne 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.
customerIdoptionalstringOnly this customer's invoices.
customerExternalReferenceoptionalstringOnly invoices of the customer with this reference.
externalReferenceoptionalstringExact match.
from, tooptionalstring (date)Issue date range (YYYY-MM-DD, SAST, inclusive).
limit, startingAfteroptionalKeyset 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#

GET/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#

GET/api/v1/invoices/{id}/pdf

Returns 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.

Download an invoice PDF
curl -o invoice.pdf \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/pdf"

Send an invoice#

POST/api/v1/invoices/{id}/send

Emails 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#

POST/api/v1/invoices/{id}/issue

Marks 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#

POST/api/v1/invoices/{id}/payments

Records money received outside CentraPoint's gateways. Payments made through a pay link are recorded automatically; don't record them again.

Offline payment fields
FieldTypeDescription
amountrequirednumberGreater than 0 and not more than the outstanding balance.
methodrequiredstringeft, cash, card, wallet or other.
referenceoptionalstringUp to 190 chars, e.g. the bank statement reference.
paidAtoptionalstring (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).

Allocation fields
FieldTypeDescription
transactionReferencerequiredstringReference (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 becomes paid or partially_paid, and invoice.paid / invoice.partially_paid is sent). It then appears in payments with source: "transaction", and in the transaction's invoice.
  • Returns 201 with the invoice; 200 (unchanged) when the payment is already allocated to this invoice, so retries are safe.
  • Rejected with 409 already_allocated when the payment belongs to another invoice, and with 400 when 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#

POST/api/v1/invoices/{id}/cancel

Voids 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#

Invoice errors
StatuserrorWhen
400invalid_requestValidation 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.
403plan_restricted / account_restrictedPlan lacks the API or Invoicing, or the account is read-only (writes).
404not_foundNo invoice with this ID or number in your organisation.
409idempotency_conflictIdempotency-Key reused with a different body.
409already_allocatedAllocation: the transaction is already allocated to another invoice.
401 / 429 / 500unauthorized / rate_limited / internal_errorSee Errors