API
API reference
Endpoint reference generated from the CentraPoint OpenAPI 3.1 specification, with code samples.
On this page
- List payment links
- Create a payment link
- Get a payment link
- List checkout sessions
- Create a checkout session
- Get a checkout session
- List coupons
- Create a coupon
- Validate a coupon
- Get a coupon
- Update a coupon
- List customers
- Create or upsert a customer
- Look up a customer
- Get a customer
- Update a customer
- Send a customer portal link, or create a sign-in link
- Get a customer's account standing
- List a customer's saved cards
- Start the hosted add-card page
- Get an add-card session
- Get a saved card
- Remove a saved card
- Make a saved card the default
- Charge a saved card
- List invoices
- Create an invoice
- Get an invoice
- Send an invoice
- Issue an invoice without emailing
- Cancel an invoice
- Record an offline payment or allocate an existing payment
- Download an invoice PDF
- List quotes
- Create a quote
- Get a quote
- Update a quote
- Delete a draft quote
- Mark a quote sent
- Mark a quote accepted
- Mark a quote declined
- Convert a quote to an invoice
- Download a quote PDF
- List credit notes
- Create a credit note
- Get a credit note
- Issue a credit note
- Void a credit note
- Apply credit to an invoice
- Pay credit back
- Download a credit note PDF
- List subscriptions
- Get a subscription
- Pause a subscription
- Resume a subscription
- Cancel a subscription
- List packages
- Create a package
- Get a package
- Update a package
- Disable a package
- Add a plan to a package
- List plans (find one by code)
- Get a plan
- Update a plan
- List customer subscriptions
- Subscribe a customer to a plan
- Get a customer subscription
- Update a customer subscription
- Pause a customer subscription
- Resume a customer subscription
- Cancel a customer subscription
- Change plan
- List products
- Create a product
- Get a product
- Update a product
- List EFT orders
- Create an EFT order
- Get an EFT order
- Upload proof of payment
- Download a proof of payment
- Cancel an EFT order
- List transactions
- Get a transaction by reference
- List receipts
- Get a receipt
- List refunds
- Get a refund
- List payouts
- Schedule a payout
- Get a payout
- Cancel a payout
- List mandates
- Create a mandate
- Get a mandate
- Update a mandate
- Issue a mandate agreement
- List reconciliation runs
- Get a reconciliation run
- List statement lines
- List Netcash accounts
- List accounting referral links
- Get your organisation and entitlements
- Check one entitlement
- Preview a change
- Reactivate a subscription
- Record your platform's period (external subscriptions)
- Add credit
- Discount the next renewal
- Cancel a scheduled change
- List items
- Add an item
- Replace the recurring items
- Update an item
- Remove an item
- Record metered usage
- List a subscription's invoices
- List a subscription's payments
- Change amount or next charge date
- Retry a failed charge
- List charges
- List migrations
- Migrate legacy subscriptions
- Get a migration
- Migration actions
- Webhook events
CentraPoint API v1.23.0 · OpenAPI 3.1.0 · Base URL https://app.centrapoint.co.za
The CentraPoint REST API lets your systems manage customers, products, invoices, quotes and credit notes, schedule Netcash payouts, create hosted payment links, checkout sessions, coupons, EFT orders, subscription packages, plans and customer subscriptions, create and manage debit order mandates, manage customers' saved cards (and charge them from your own billing system) and read their account standing, list payments, receipts and refunds (with PDFs), check your organisation's entitlements and read reconciliation results. Every API key may make 120 requests per minute; responses report usage in X-RateLimit-* headers. All requests are authenticated with a tenant-scoped API key sent as a Bearer token. API access requires a plan that includes the REST API (Growth or higher).
Outbound webhooks that CentraPoint sends to your endpoints are described in the webhooks section. Gateway notification URLs (/api/webhooks/{type}) are called by payment gateways, not by API clients, and are therefore not part of this specification.
Download the machine-readable specification: openapi.json. Import it into Insomnia or a code generator.
Download Postman collection Every endpoint below, ready to send. See Use the Postman collection to set it up.
/api/v1/payment-linksPOSTCreate a payment link/api/v1/payment-linksGETGet a payment link/api/v1/payment-links/{id}GETList checkout sessions/api/v1/checkout-sessionsPOSTCreate a checkout session/api/v1/checkout-sessionsGETGet a checkout session/api/v1/checkout-sessions/{id}GETList coupons/api/v1/couponsPOSTCreate a coupon/api/v1/couponsPOSTValidate a coupon/api/v1/coupons/validateGETGet a coupon/api/v1/coupons/{id}PATCHUpdate a coupon/api/v1/coupons/{id}GETList customers/api/v1/customersPOSTCreate or upsert a customer/api/v1/customersGETLook up a customer/api/v1/customers/lookupGETGet a customer/api/v1/customers/{id}PATCHUpdate a customer/api/v1/customers/{id}POSTSend a customer portal link, or create a sign-in link/api/v1/customers/{id}/portal-linkGETGet a customer's account standing/api/v1/customers/{id}/standingGETList a customer's saved cards/api/v1/customers/{id}/cardsPOSTStart the hosted add-card page/api/v1/customers/{id}/cards/setupGETGet an add-card session/api/v1/customers/{id}/cards/setup/{sessionId}GETGet a saved card/api/v1/customers/{id}/cards/{cardId}DELETERemove a saved card/api/v1/customers/{id}/cards/{cardId}POSTMake a saved card the default/api/v1/customers/{id}/cards/{cardId}/defaultPOSTCharge a saved card/api/v1/customers/{id}/cards/{cardId}/chargesGETList invoices/api/v1/invoicesPOSTCreate an invoice/api/v1/invoicesGETGet an invoice/api/v1/invoices/{id}POSTSend an invoice/api/v1/invoices/{id}/sendPOSTIssue an invoice without emailing/api/v1/invoices/{id}/issuePOSTCancel an invoice/api/v1/invoices/{id}/cancelPOSTRecord an offline payment or allocate an existing payment/api/v1/invoices/{id}/paymentsGETDownload an invoice PDF/api/v1/invoices/{id}/pdfGETList quotes/api/v1/quotesPOSTCreate a quote/api/v1/quotesGETGet a quote/api/v1/quotes/{id}PATCHUpdate a quote/api/v1/quotes/{id}DELETEDelete a draft quote/api/v1/quotes/{id}POSTMark a quote sent/api/v1/quotes/{id}/sendPOSTMark a quote accepted/api/v1/quotes/{id}/acceptPOSTMark a quote declined/api/v1/quotes/{id}/declinePOSTConvert a quote to an invoice/api/v1/quotes/{id}/convertGETDownload a quote PDF/api/v1/quotes/{id}/pdfGETList credit notes/api/v1/credit-notesPOSTCreate a credit note/api/v1/credit-notesGETGet a credit note/api/v1/credit-notes/{id}POSTIssue a credit note/api/v1/credit-notes/{id}/issuePOSTVoid a credit note/api/v1/credit-notes/{id}/voidPOSTApply credit to an invoice/api/v1/credit-notes/{id}/applyPOSTPay credit back/api/v1/credit-notes/{id}/refundGETDownload a credit note PDF/api/v1/credit-notes/{id}/pdfGETList subscriptions/api/v1/subscriptionsGETGet a subscription/api/v1/subscriptions/{id}POSTPause a subscription/api/v1/subscriptions/{id}/pausePOSTResume a subscription/api/v1/subscriptions/{id}/resumePOSTCancel a subscription/api/v1/subscriptions/{id}/cancelGETList packages/api/v1/packagesPOSTCreate a package/api/v1/packagesGETGet a package/api/v1/packages/{id}PATCHUpdate a package/api/v1/packages/{id}DELETEDisable a package/api/v1/packages/{id}POSTAdd a plan to a package/api/v1/packages/{id}/plansGETList plans (find one by code)/api/v1/plansGETGet a plan/api/v1/plans/{id}PATCHUpdate a plan/api/v1/plans/{id}GETList customer subscriptions/api/v1/customer-subscriptionsPOSTSubscribe a customer to a plan/api/v1/customer-subscriptionsGETGet a customer subscription/api/v1/customer-subscriptions/{id}PATCHUpdate a customer subscription/api/v1/customer-subscriptions/{id}POSTPause a customer subscription/api/v1/customer-subscriptions/{id}/pausePOSTResume a customer subscription/api/v1/customer-subscriptions/{id}/resumePOSTCancel a customer subscription/api/v1/customer-subscriptions/{id}/cancelPOSTChange plan/api/v1/customer-subscriptions/{id}/change-planGETList products/api/v1/productsPOSTCreate a product/api/v1/productsGETGet a product/api/v1/products/{id}PATCHUpdate a product/api/v1/products/{id}GETList EFT orders/api/v1/eft-ordersPOSTCreate an EFT order/api/v1/eft-ordersGETGet an EFT order/api/v1/eft-orders/{id}POSTUpload proof of payment/api/v1/eft-orders/{id}/proofGETDownload a proof of payment/api/v1/eft-orders/{id}/proofs/{proofId}POSTCancel an EFT order/api/v1/eft-orders/{id}/cancelGETList transactions/api/v1/transactionsGETGet a transaction by reference/api/v1/transactions/{reference}GETList receipts/api/v1/receiptsGETGet a receipt/api/v1/receipts/{id}GETList refunds/api/v1/refundsGETGet a refund/api/v1/refunds/{id}GETList payouts/api/v1/payoutsPOSTSchedule a payout/api/v1/payoutsGETGet a payout/api/v1/payouts/{id}POSTCancel a payout/api/v1/payouts/{id}/cancelGETList mandates/api/v1/mandatesPOSTCreate a mandate/api/v1/mandatesGETGet a mandate/api/v1/mandates/{id}PATCHUpdate a mandate/api/v1/mandates/{id}POSTIssue a mandate agreement/api/v1/mandates/{id}/agreementGETList reconciliation runs/api/v1/reconciliation/runsGETGet a reconciliation run/api/v1/reconciliation/runs/{id}GETList statement lines/api/v1/reconciliation/linesGETList Netcash accounts/api/v1/reconciliation/accountsGETList accounting referral links/api/v1/accounting/referral-linksGETGet your organisation and entitlements/api/v1/meGETCheck one entitlement/api/v1/entitlements/{key}POSTPreview a change/api/v1/customer-subscriptions/{id}/preview-changePOSTReactivate a subscription/api/v1/customer-subscriptions/{id}/reactivatePOSTRecord your platform's period (external subscriptions)/api/v1/customer-subscriptions/{id}/sync-periodPOSTAdd credit/api/v1/customer-subscriptions/{id}/creditPOSTDiscount the next renewal/api/v1/customer-subscriptions/{id}/discountDELETECancel a scheduled change/api/v1/customer-subscriptions/{id}/pending-changeGETList items/api/v1/customer-subscriptions/{id}/itemsPOSTAdd an item/api/v1/customer-subscriptions/{id}/itemsPUTReplace the recurring items/api/v1/customer-subscriptions/{id}/itemsPATCHUpdate an item/api/v1/customer-subscriptions/{id}/items/{itemId}DELETERemove an item/api/v1/customer-subscriptions/{id}/items/{itemId}POSTRecord metered usage/api/v1/customer-subscriptions/{id}/items/{itemId}/usageGETList a subscription's invoices/api/v1/customer-subscriptions/{id}/invoicesGETList a subscription's payments/api/v1/customer-subscriptions/{id}/paymentsPOSTChange amount or next charge date/api/v1/subscriptions/{id}/updatePOSTRetry a failed charge/api/v1/subscriptions/{id}/retryGETList charges/api/v1/subscriptions/{id}/chargesGETList migrations/api/v1/subscriptions/migrationsPOSTMigrate legacy subscriptions/api/v1/subscriptions/migrationsGETGet a migration/api/v1/subscriptions/migrations/{id}POSTMigration actions/api/v1/subscriptions/migrations/{id}/{action}List payment links#
/api/v1/payment-linksReturns your organisation's payment links, newest first, each with the payments made through it (up to 50 per link). Filter by externalReference to find the link for one of your orders and discover its payment references.
Query parameters#
| Field | Type | Description |
|---|---|---|
externalReference | string | Only links with exactly this external reference (leading/trailing whitespace ignored). |
limit | integer | Maximum number of links to return, 1–100. Invalid or missing values fall back to 20; values out of range are clamped. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Matching links.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | PaymentLinkWithPayments[] | Show fields
|
{
"data": [
{
"id": "cmg1k2x3y0001abcd1234efgh",
"url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
"title": "Website hosting - October",
"description": "Monthly hosting for example.co.za",
"amount": 499,
"currency": "ZAR",
"externalReference": "ORDER-1001",
"singleUse": true,
"active": false,
"expiresAt": "2026-10-31T21:59:59.000Z",
"paidCount": 1,
"createdAt": "2026-09-25T08:10:02.114Z",
"payments": [
{
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 499,
"currency": "ZAR",
"paidAt": "2026-09-25T08:14:03.512Z",
"createdAt": "2026-09-25T08:12:47.020Z"
},
{
"reference": "CP-20260925-41D07E2A",
"status": "cancelled",
"amount": 499,
"currency": "ZAR",
"paidAt": null,
"createdAt": "2026-09-25T08:11:15.873Z"
}
],
"returnUrl": null,
"metadata": {},
"recurring": null,
"subscription": null
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/payment-links?externalReference=ORDER-1001" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a payment link#
/api/v1/payment-linksCreates a hosted payment link at /pay/{token}. When customerEmail is supplied, the link is attached to the existing customer with that email address in your organisation, or a new customer is created (subject to your plan's customer limit).
Requires the API and Payment links features on your plan, and an account that is not read-only (suspended, cancelled or expired trial).
Pass externalReference (your order ID) so you can later find the link and the payment references made through it with GET /api/v1/payment-links?externalReference=.
Unknown body fields are ignored. This endpoint is not idempotent: retrying a request creates another link.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
titlerequired | string | Shown to the payer. Leading and trailing whitespace is trimmed before the length check. 1–100 chars | |||||||||
description | string | Optional longer text shown under the title on the payment page. max 255 chars | |||||||||
amountrequired | number | Amount in major units (e.g. 499.00 rand). Rounded to 2 decimal places. Gateways may enforce their own minimums or whole-unit amounts. > 0 · ≤ 10 000 000 | |||||||||
currency | string | ISO 4217 currency code, upper-cased by the server. Must be a valid ISO 4217 code and accepted by at least one of your enabled checkout gateways (or, for once-off links, by your Manual EFT gateway); otherwise the request fails with 400 invalid_request. default "ZAR" | |||||||||
externalReference | string | Your own identifier for this link, e.g. your order or invoice number. Trimmed before validation. Not required to be unique. Use it with 1–100 chars | |||||||||
returnUrl | string (uri) | Where to send the payer after a final outcome. Must be https and on an origin allow-listed under Settings → API keys → Allowed return URLs. CentraPoint appends max 1000 chars | |||||||||
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||
customerId | string | Attach an existing customer (takes precedence over customerEmail). | |||||||||
recurring | object | Start a gateway-managed subscription when the link is paid. Requires a plan with recurring billing and an enabled gateway that supports it (PayFast, Netcash Pay Now); only such gateways are offered to the payer. Can be combined with Show fields
| |||||||||
productId | string | ID of a product in your organisation. Recurring products start a gateway-managed subscription at checkout (plan and gateway permitting). | |||||||||
invoiceId | string | ID of an invoice in your organisation. Successful payments are applied to the invoice. With | |||||||||
customerEmail | string (email) | Attach the link to a customer. Matched case-insensitively against existing customers; a new customer is created if none exists. | |||||||||
customerFirstName | string | Used only when a new customer is created. Defaults to the part of the email before @. max 100 chars | |||||||||
customerLastName | string | Used only when a new customer is created. max 100 chars | |||||||||
singleUse | boolean | When true, the link is deactivated after its first successful payment. default true | |||||||||
expiresAt | string (date-time) | ISO 8601 timestamp with | |||||||||
saveCard | boolean | Save the card the customer pays this link with as their default card (gateways that save cards, e.g. Netcash Pay Now). Ignored since 1.21.0: saved cards are no longer charged or saved. Bill subscriptions with a recurring link ( default false |
Responses#
201Payment link created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Payment link ID. | |||||||||
urlrequired | string (uri) | Hosted payment page to send to the payer: https://app.centrapoint.co.za/pay/{token}. | |||||||||
titlerequired | string | ||||||||||
descriptionrequired | string | null | ||||||||||
amountrequired | number | Amount after rounding to 2 decimal places. | |||||||||
currencyrequired | string | Upper-case ISO 4217 code. | |||||||||
externalReferencerequired | string | null | Your identifier, as supplied when the link was created. | |||||||||
returnUrlrequired | string (uri) | null | ||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||
recurringrequired | null | object | Show fields
| |||||||||
singleUserequired | boolean | Whether the link deactivates after its first successful payment. | |||||||||
saveCardrequired | boolean | The link saves the card it is paid with as the customer's default card (since 1.20.0). | |||||||||
activerequired | boolean | False once deactivated (in the dashboard, or after a single-use link is paid). | |||||||||
expiresAtrequired | string (date-time) | null | ||||||||||
paidCountrequired | integer | Number of successful payments made through the link. | |||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg1k2x3y0001abcd1234efgh",
"url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
"title": "Website hosting - October",
"description": "Monthly hosting for example.co.za",
"amount": 499,
"currency": "ZAR",
"externalReference": "ORDER-1001",
"singleUse": true,
"active": true,
"expiresAt": "2026-10-31T21:59:59.000Z",
"paidCount": 0,
"createdAt": "2026-09-25T08:10:02.114Z",
"returnUrl": "https://shop.example.co.za/checkout/done",
"metadata": {
"crmId": "0061x00000AbCdE"
},
"recurring": null
}400The body failed validation (`issues` lists each problem), or a business rule failed: unknown product/invoice, invalid or unsupported currency, or `expiresAt` not in the future / more than 1 year ahead.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body",
"issues": [
{
"origin": "number",
"code": "too_small",
"minimum": 0,
"inclusive": false,
"path": [
"amount"
],
"message": "Too small: expected number to be >0"
}
]
}{
"error": "invalid_request",
"message": "Product not found"
}{
"error": "invalid_request",
"message": "None of your enabled payment gateways accept USD. Enable a gateway that supports USD first."
}{
"error": "invalid_request",
"message": "expiresAt must be in the future"
}{
"error": "invalid_request",
"message": "returnUrl origin https://shop.example.co.za is not allowed - add it under Settings > API keys > Allowed return URLs"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Your plan does not include the API or payment links (`plan_restricted`), a plan quota such as the customer limit was reached (`plan_limit`), or the account is read-only (`account_restricted`).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}{
"error": "plan_limit",
"message": "Customers limit reached (2000/2000) on the Growth plan. Upgrade under Settings > Billing."
}{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}413Request body larger than 100 000 characters.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Request body too large"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/payment-links" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"title": "Pro plan",
"amount": 499,
"externalReference": "SUB-ACME-PRO",
"customerId": "cmg2c0s7t0003cust0001abcd",
"recurring": {
"frequency": "monthly"
},
"singleUse": true
}'Get a payment link#
/api/v1/payment-links/{id}Returns one payment link in your organisation with the payments made through it (newest first, up to 100).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Payment link ID returned when the link was created. |
Responses#
200The payment link.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Payment link ID. | |||||||||||||||||||||
urlrequired | string (uri) | Hosted payment page to send to the payer: https://app.centrapoint.co.za/pay/{token}. | |||||||||||||||||||||
titlerequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
amountrequired | number | Amount after rounding to 2 decimal places. | |||||||||||||||||||||
currencyrequired | string | Upper-case ISO 4217 code. | |||||||||||||||||||||
externalReferencerequired | string | null | Your identifier, as supplied when the link was created. | |||||||||||||||||||||
returnUrlrequired | string (uri) | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
recurringrequired | null | object | Show fields
| |||||||||||||||||||||
singleUserequired | boolean | Whether the link deactivates after its first successful payment. | |||||||||||||||||||||
saveCardrequired | boolean | The link saves the card it is paid with as the customer's default card (since 1.20.0). | |||||||||||||||||||||
activerequired | boolean | False once deactivated (in the dashboard, or after a single-use link is paid). | |||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidCountrequired | integer | Number of successful payments made through the link. | |||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||
paymentsrequired | LinkPayment[] | Checkout attempts made through the link, newest first. Each attempt is a transaction with its own reference. Show fields
| |||||||||||||||||||||
subscription | null | object | The latest subscription started by this link, or null. Show fields
|
{
"id": "cmg1k2x3y0001abcd1234efgh",
"url": "https://app.centrapoint.co.za/pay/Xb7kP2qR9sLm4TvWz8Yc",
"title": "Website hosting - October",
"description": "Monthly hosting for example.co.za",
"amount": 499,
"currency": "ZAR",
"externalReference": "ORDER-1001",
"singleUse": true,
"active": false,
"expiresAt": "2026-10-31T21:59:59.000Z",
"paidCount": 1,
"createdAt": "2026-09-25T08:10:02.114Z",
"payments": [
{
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 499,
"currency": "ZAR",
"paidAt": "2026-09-25T08:14:03.512Z",
"createdAt": "2026-09-25T08:12:47.020Z"
},
{
"reference": "CP-20260925-41D07E2A",
"status": "cancelled",
"amount": 499,
"currency": "ZAR",
"paidAt": null,
"createdAt": "2026-09-25T08:11:15.873Z"
}
],
"returnUrl": null,
"metadata": {},
"recurring": null,
"subscription": null
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No payment link with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Payment link not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/payment-links/cmg1k2x3y0001abcd1234efgh" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List checkout sessions#
/api/v1/checkout-sessionsNewest first.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | Filter by reported status: One of: |
customerId | string | Filter by customer. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Sessions.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | CheckoutSession[] | Show fields
|
{
"data": [
{
"id": "cmg5k1s2e0010cks0001abcd",
"object": "checkout_session",
"status": "pending",
"source": "api",
"checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"planId": "cmg4p1a2b0002pln0001abcd",
"productId": null,
"customerId": null,
"subscriptionId": null,
"couponCode": "WELCOME10",
"returnUrl": "https://www.example.co.za/thanks",
"prefill": {
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi"
},
"metadata": {
"signupId": "SU-9921"
},
"transaction": null,
"expiresAt": "2026-09-29T08:30:00.000Z",
"usedAt": null,
"createdAt": "2026-09-28T08:30:00.000Z",
"updatedAt": "2026-09-28T08:30:00.000Z"
}
]
}400Invalid status.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of pending, completed, failed, expired"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/checkout-sessions" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a checkout session#
/api/v1/checkout-sessionsReturns a pre-filled hosted checkout URL for a package (optionally with a preselected plan) or a product, valid for 24 hours. Follow the outcome with GET /api/v1/checkout-sessions/{id} or the checkout.completed / checkout.failed webhooks.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
packageId | string | max 40 chars | |||||||||||||||||||||
planId | string | Preselects a plan; the package is derived when packageId is omitted. Plans with a call to action or contact option can't be sold through checkout. max 40 chars | |||||||||||||||||||||
productId | string | max 40 chars | |||||||||||||||||||||
returnUrl | string | https URL whose origin is allow-listed under Settings → API keys → Allowed return URLs. max 1000 chars | |||||||||||||||||||||
customer | object | Payer details to pre-fill. Show fields
| |||||||||||||||||||||
client | object | Alias of customer. Show fields
| |||||||||||||||||||||
couponCode | string | Must be an enabled coupon; needs Coupons in your plan. 1–50 chars | |||||||||||||||||||||
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
Responses#
201The session.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||||||||
objectrequired | string | One of: | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
sourcerequired | string |
One of: | |||||||||||||||||||||||||||
checkoutUrlrequired | string | ||||||||||||||||||||||||||||
packageIdrequired | string | null | ||||||||||||||||||||||||||||
planIdrequired | string | null | Preselected plan. | |||||||||||||||||||||||||||
productIdrequired | string | null | ||||||||||||||||||||||||||||
customerIdrequired | string | null | Set once the payer's details are known. | |||||||||||||||||||||||||||
subscriptionIdrequired | string | null | Customer subscription created by the checkout. | |||||||||||||||||||||||||||
couponCoderequired | string | null | ||||||||||||||||||||||||||||
returnUrlrequired | string | null | ||||||||||||||||||||||||||||
prefillrequired | object | Show fields
| |||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||||||||
transactionrequired | object | null | Show fields
| |||||||||||||||||||||||||||
expiresAtrequired | string (date-time) | ||||||||||||||||||||||||||||
usedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | ||||||||||||||||||||||||||||
sessionIdrequired | string | Same as id. |
{
"id": "cmg5k1s2e0010cks0001abcd",
"object": "checkout_session",
"status": "pending",
"source": "api",
"checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"planId": "cmg4p1a2b0002pln0001abcd",
"productId": null,
"customerId": null,
"subscriptionId": null,
"couponCode": "WELCOME10",
"returnUrl": "https://www.example.co.za/thanks",
"prefill": {
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi"
},
"metadata": {
"signupId": "SU-9921"
},
"transaction": null,
"expiresAt": "2026-09-29T08:30:00.000Z",
"usedAt": null,
"createdAt": "2026-09-28T08:30:00.000Z",
"updatedAt": "2026-09-28T08:30:00.000Z",
"sessionId": "cmg5k1s2e0010cks0001abcd"
}400Validation failed: nothing or both kinds of target, unknown/disabled package, plan or product, returnUrl not https or not allow-listed, invalid coupon.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "returnUrl origin https://www.example.co.za is not allowed - add it under Settings > API keys > Allowed return URLs"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403`plan_restricted`: no REST API. `plan_limit`: a package checkout needs Recurring billing, a product checkout Payment links. `account_restricted`: read-only account.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_limit",
"message": "Recurring card billing is not included in the Starter plan. Upgrade under Settings > Billing."
}409Idempotency-Key reused with a different body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/checkout-sessions" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"planId": "cmg4p1a2b0002pln0001abcd",
"returnUrl": "https://www.example.co.za/thanks",
"customer": {
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi"
},
"couponCode": "WELCOME10",
"metadata": {
"signupId": "SU-9921"
}
}'Get a checkout session#
/api/v1/checkout-sessions/{id}Status, the payment (reference, status, amounts) and the resulting subscription.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The session.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||||||||
objectrequired | string | One of: | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
sourcerequired | string |
One of: | |||||||||||||||||||||||||||
checkoutUrlrequired | string | null | Hosted checkout URL while the session is pending or failed and not expired (null for | |||||||||||||||||||||||||||
packageIdrequired | string | null | ||||||||||||||||||||||||||||
planIdrequired | string | null | Preselected plan. | |||||||||||||||||||||||||||
productIdrequired | string | null | ||||||||||||||||||||||||||||
customerIdrequired | string | null | Set once the payer's details are known. | |||||||||||||||||||||||||||
subscriptionIdrequired | string | null | Customer subscription created by the checkout. | |||||||||||||||||||||||||||
couponCoderequired | string | null | ||||||||||||||||||||||||||||
returnUrlrequired | string | null | ||||||||||||||||||||||||||||
prefillrequired | object | Show fields
| |||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||||||||
transactionrequired | object | null | Show fields
| |||||||||||||||||||||||||||
expiresAtrequired | string (date-time) | ||||||||||||||||||||||||||||
usedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg5k1s2e0010cks0001abcd",
"object": "checkout_session",
"status": "pending",
"source": "api",
"checkoutUrl": "https://app.centrapoint.co.za/c/acme/package/cmg4p1a2b0001pkg0001abcd?session=Xk3…",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"planId": "cmg4p1a2b0002pln0001abcd",
"productId": null,
"customerId": null,
"subscriptionId": null,
"couponCode": "WELCOME10",
"returnUrl": "https://www.example.co.za/thanks",
"prefill": {
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi"
},
"metadata": {
"signupId": "SU-9921"
},
"transaction": null,
"expiresAt": "2026-09-29T08:30:00.000Z",
"usedAt": null,
"createdAt": "2026-09-28T08:30:00.000Z",
"updatedAt": "2026-09-28T08:30:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No session with this ID.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Checkout session not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/checkout-sessions/cmg5k1s2e0010cks0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List coupons#
/api/v1/couponsNewest first, with redemption counts.
Query parameters#
| Field | Type | Description |
|---|---|---|
code | string | Exact code (case-insensitive). |
enabled | string | Only enabled/disabled coupons. One of: |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Coupons.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Coupon[] | Show fields
|
{
"data": [
{
"id": "cmg5c0u1p0011cpn0001abcd",
"object": "coupon",
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"currency": null,
"appliesTo": "any",
"productIds": [],
"planIds": [],
"duration": "once",
"durationCycles": null,
"validFrom": null,
"validTo": "2026-12-31T21:59:59.000Z",
"maxRedemptions": 500,
"maxPerCustomer": 1,
"minAmount": null,
"enabled": true,
"redemptions": {
"redeemed": 12,
"pending": 1
},
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Coupons are not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/coupons" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a coupon#
/api/v1/couponsRequest headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
coderequired | string | 3–50 letters, digits, - or _; stored upper-case. |
description | string | null | max 500 chars |
typerequired | string | One of: |
valuerequired | number | Percentage (at most 100) or fixed amount. > 0 · ≤ 1 000 000 |
currency | string | null | Required for fixed coupons. |
appliesTo | string | One of: default "any" |
productIds | string[] | Limit to these products (empty = all). IDs not in your organisation are dropped. |
planIds | string[] | Limit to these plans (empty = all). IDs not in your organisation are dropped. |
duration | string | For subscriptions: first charge only, One of: default "once" |
durationCycles | integer | null | Required for repeating. ≥ 1 · ≤ 120 |
validFrom | string (date-time) | null | |
validTo | string (date-time) | null | After validFrom. |
maxRedemptions | integer | null | ≥ 1 · ≤ 10 000 000 |
maxPerCustomer | integer | null | ≥ 1 · ≤ 10 000 |
minAmount | number | null | ≥ 0 · ≤ 100 000 000 |
enabled | boolean | default true |
Responses#
201The coupon.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||
coderequired | string | |||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||
valuerequired | number | Percentage (at most 100) or fixed amount. | ||||||||||||||||||||||||
currencyrequired | string | null | Required for fixed coupons. | ||||||||||||||||||||||||
appliesTorequired | string | One of: | ||||||||||||||||||||||||
productIdsrequired | string[] | Limit to these products (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
planIdsrequired | string[] | Limit to these plans (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
durationrequired | string | For subscriptions: first charge only, One of: | ||||||||||||||||||||||||
durationCyclesrequired | integer | null | Required for repeating. | ||||||||||||||||||||||||
validFromrequired | string (date-time) | null | |||||||||||||||||||||||||
validTorequired | string (date-time) | null | After validFrom. | ||||||||||||||||||||||||
maxRedemptionsrequired | integer | null | |||||||||||||||||||||||||
maxPerCustomerrequired | integer | null | |||||||||||||||||||||||||
minAmountrequired | number | null | |||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||
redemptionsrequired | object | Usage counts: Show fields
| ||||||||||||||||||||||||
recentRedemptions | CouponRedemption[] | Only with Show fields
| ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg5c0u1p0011cpn0001abcd",
"object": "coupon",
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"currency": null,
"appliesTo": "any",
"productIds": [],
"planIds": [],
"duration": "once",
"durationCycles": null,
"validFrom": null,
"validTo": "2026-12-31T21:59:59.000Z",
"maxRedemptions": 500,
"maxPerCustomer": 1,
"minAmount": null,
"enabled": true,
"redemptions": {
"redeemed": 0,
"pending": 0
},
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed (code format, percentage over 100, fixed without currency, repeating without durationCycles, validTo before validFrom, duplicate code…).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A fixed discount needs a currency"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Coupons are not included in your plan"
}409Idempotency-Key reused with a different body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/coupons" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"duration": "once",
"validTo": "2026-12-31T23:59:59+02:00",
"maxRedemptions": 500,
"maxPerCustomer": 1
}'Validate a coupon#
/api/v1/coupons/validateWould this code apply to a product or plan (for this customer)? Nothing is reserved or redeemed. An unusable code is a 200 with valid: false. The Idempotency-Key header is not used.
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
coderequired | string | 1–50 chars |
productId | string | max 40 chars |
planId | string | max 40 chars |
amount | number | Price before discount and tax; default the product/plan price. > 0 · ≤ 100 000 000 |
currency | string | Default the product/plan currency. exactly 3 chars |
customerId | string | For per-customer limits. max 40 chars |
customerEmail | string (email) | For per-customer limits. max 200 chars |
Responses#
200The result.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
validrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
discount | number | valid: discount on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount | number | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total | number | amount − discount. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
coupon | Coupon | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reason | string | invalid: why. One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
message | string | invalid: customer-safe message. |
{
"valid": true,
"discount": 49.9,
"amount": 499,
"total": 449.1,
"currency": "ZAR",
"coupon": {
"id": "cmg5c0u1p0011cpn0001abcd",
"object": "coupon",
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"currency": null,
"appliesTo": "any",
"productIds": [],
"planIds": [],
"duration": "once",
"durationCycles": null,
"validFrom": null,
"validTo": "2026-12-31T21:59:59.000Z",
"maxRedemptions": 500,
"maxPerCustomer": 1,
"minAmount": null,
"enabled": true,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
}{
"valid": false,
"reason": "expired",
"message": "This coupon has expired"
}400Validation failed (e.g. not exactly one of productId/planId).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Coupons are not included in your plan"
}404Product or plan not found.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Plan not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/coupons/validate" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "WELCOME10",
"planId": "cmg4p1a2b0002pln0001abcd",
"customerEmail": "[email protected]"
}'Get a coupon#
/api/v1/coupons/{id}?include=redemptions adds recentRedemptions: the latest 100 redemptions (id, status, discountAmount, customerId, subscriptionId, transactionReference, createdAt). redemptions stays the counts object.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Query parameters#
| Field | Type | Description |
|---|---|---|
include | string |
One of: |
Responses#
200The coupon.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||
coderequired | string | |||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||
valuerequired | number | Percentage (at most 100) or fixed amount. | ||||||||||||||||||||||||
currencyrequired | string | null | Required for fixed coupons. | ||||||||||||||||||||||||
appliesTorequired | string | One of: | ||||||||||||||||||||||||
productIdsrequired | string[] | Limit to these products (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
planIdsrequired | string[] | Limit to these plans (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
durationrequired | string | For subscriptions: first charge only, One of: | ||||||||||||||||||||||||
durationCyclesrequired | integer | null | Required for repeating. | ||||||||||||||||||||||||
validFromrequired | string (date-time) | null | |||||||||||||||||||||||||
validTorequired | string (date-time) | null | After validFrom. | ||||||||||||||||||||||||
maxRedemptionsrequired | integer | null | |||||||||||||||||||||||||
maxPerCustomerrequired | integer | null | |||||||||||||||||||||||||
minAmountrequired | number | null | |||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||
redemptionsrequired | object | Usage counts: Show fields
| ||||||||||||||||||||||||
recentRedemptions | CouponRedemption[] | Only with Show fields
| ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg5c0u1p0011cpn0001abcd",
"object": "coupon",
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"currency": null,
"appliesTo": "any",
"productIds": [],
"planIds": [],
"duration": "once",
"durationCycles": null,
"validFrom": null,
"validTo": "2026-12-31T21:59:59.000Z",
"maxRedemptions": 500,
"maxPerCustomer": 1,
"minAmount": null,
"enabled": true,
"redemptions": {
"redeemed": 12,
"pending": 1
},
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Coupons are not included in your plan"
}404No coupon with this ID.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Coupon not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/coupons/cmg5c0u1p0011cpn0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a coupon#
/api/v1/coupons/{id}Any create field, validated after merging with the stored coupon. Send {"enabled": false} to disable; there is no DELETE. The Idempotency-Key header is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
code | string | 3–50 letters, digits, - or _; stored upper-case. |
description | string | null | max 500 chars |
type | string | One of: |
value | number | Percentage (at most 100) or fixed amount. > 0 · ≤ 1 000 000 |
currency | string | null | Required for fixed coupons. |
appliesTo | string | One of: default "any" |
productIds | string[] | Limit to these products (empty = all). IDs not in your organisation are dropped. |
planIds | string[] | Limit to these plans (empty = all). IDs not in your organisation are dropped. |
duration | string | For subscriptions: first charge only, One of: default "once" |
durationCycles | integer | null | Required for repeating. ≥ 1 · ≤ 120 |
validFrom | string (date-time) | null | |
validTo | string (date-time) | null | After validFrom. |
maxRedemptions | integer | null | ≥ 1 · ≤ 10 000 000 |
maxPerCustomer | integer | null | ≥ 1 · ≤ 10 000 |
minAmount | number | null | ≥ 0 · ≤ 100 000 000 |
enabled | boolean | default true |
Responses#
200The updated coupon.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||
coderequired | string | |||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||
valuerequired | number | Percentage (at most 100) or fixed amount. | ||||||||||||||||||||||||
currencyrequired | string | null | Required for fixed coupons. | ||||||||||||||||||||||||
appliesTorequired | string | One of: | ||||||||||||||||||||||||
productIdsrequired | string[] | Limit to these products (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
planIdsrequired | string[] | Limit to these plans (empty = all). IDs not in your organisation are dropped. | ||||||||||||||||||||||||
durationrequired | string | For subscriptions: first charge only, One of: | ||||||||||||||||||||||||
durationCyclesrequired | integer | null | Required for repeating. | ||||||||||||||||||||||||
validFromrequired | string (date-time) | null | |||||||||||||||||||||||||
validTorequired | string (date-time) | null | After validFrom. | ||||||||||||||||||||||||
maxRedemptionsrequired | integer | null | |||||||||||||||||||||||||
maxPerCustomerrequired | integer | null | |||||||||||||||||||||||||
minAmountrequired | number | null | |||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||
redemptionsrequired | object | Usage counts: Show fields
| ||||||||||||||||||||||||
recentRedemptions | CouponRedemption[] | Only with Show fields
| ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg5c0u1p0011cpn0001abcd",
"object": "coupon",
"code": "WELCOME10",
"description": "10% off the first month",
"type": "percent",
"value": 10,
"currency": null,
"appliesTo": "any",
"productIds": [],
"planIds": [],
"duration": "once",
"durationCycles": null,
"validFrom": null,
"validTo": "2026-12-31T21:59:59.000Z",
"maxRedemptions": 500,
"maxPerCustomer": 1,
"minAmount": null,
"enabled": false,
"redemptions": {
"redeemed": 12,
"pending": 1
},
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A percentage cannot be more than 100"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No REST API or Coupons in your plan (`plan_restricted`), or the account is read-only (`account_restricted`, writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Coupons are not included in your plan"
}404No coupon with this ID.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Coupon not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/coupons/cmg5c0u1p0011cpn0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'List customers#
/api/v1/customersNewest first, keyset paginated (limit, startingAfter; the response has hasMore and nextCursor). Filters combine.
Query parameters#
| Field | Type | Description |
|---|---|---|
q | string | Search (up to 100 characters): every word must appear (case-insensitive) in the first or last name, company, email, billing email, accountCode or externalReference. max 100 chars |
externalReference | string | Exact match on your customer ID. |
email | string | Exact match (case-insensitive). |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200Customers.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Customer[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | |||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}400`q` longer than 100 characters, or `startingAfter` is not an id from this list.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "startingAfter is not a valid id"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access (or the feature) is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create or upsert a customer#
/api/v1/customersWithout externalReference: creates a customer (201). With externalReference: upsert keyed on it — updates the customer with that reference (200), otherwise adopts an existing customer with the same email and no reference (200), otherwise creates one (201). Available on any plan with API access; creating counts towards your customer limit.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
externalReference | string | Your ID. When set, the request is an upsert keyed on it. 1–190 chars |
emailrequired | string (email) | Stored lower-cased. max 200 chars |
firstNamerequired | string | 1–100 chars |
lastName | string | null | max 100 chars |
company | string | null | max 200 chars |
vatNumber | string | null | max 30 chars |
phone | string | null | max 30 chars |
address | string | null | max 1000 chars |
metadata | MetadataInput | null | |
contactType | string | Default One of: |
billingEmail | string (email) | null | Separate billing address. Subscription emails are sent here instead of max 320 chars |
Responses#
200Existing customer updated (upsert).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
accountCoderequired | string | Customer account code assigned by CentraPoint. |
externalReferencerequired | string | null | Your ID for the customer. |
contactTyperequired | string | One of: |
emailrequired | string | |
billingEmailrequired | string | null | Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs. |
firstNamerequired | string | |
lastNamerequired | string | null | |
companyrequired | string | null | |
vatNumberrequired | string | null | |
phonerequired | string | null | |
addressrequired | string | null | |
activerequired | boolean | |
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"contactType": "company",
"email": "[email protected]",
"billingEmail": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}201Customer created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
accountCoderequired | string | Customer account code assigned by CentraPoint. |
externalReferencerequired | string | null | Your ID for the customer. |
contactTyperequired | string | One of: |
emailrequired | string | |
billingEmailrequired | string | null | Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs. |
firstNamerequired | string | |
lastNamerequired | string | null | |
companyrequired | string | null | |
vatNumberrequired | string | null | |
phonerequired | string | null | |
addressrequired | string | null | |
activerequired | boolean | |
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"contactType": "company",
"email": "[email protected]",
"billingEmail": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}400Validation failed or invalid metadata.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body",
"issues": [
{
"code": "invalid_format",
"format": "email",
"path": [
"email"
],
"message": "Invalid email address"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API, customer limit reached (`plan_limit`), or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_limit",
"message": "Customers limit reached (2000/2000) on the Growth plan. Upgrade under Settings > Billing."
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customers" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"externalReference": "CRM-1001",
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"metadata": {
"crmId": "0061x00000AbCdE"
}
}'Look up a customer#
/api/v1/customers/lookupExact match on exactly one of email, externalReference or accountCode. Returns the customer, or 404. When several customers share an email, the oldest is returned.
Query parameters#
| Field | Type | Description |
|---|---|---|
email | string | Exact match, case-insensitive (up to 200 characters). |
externalReference | string | Exact match (up to 190 characters). |
accountCode | string | Exact match, e.g. |
Responses#
200The customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
accountCoderequired | string | Customer account code assigned by CentraPoint. |
externalReferencerequired | string | null | Your ID for the customer. |
contactTyperequired | string | One of: |
emailrequired | string | |
billingEmailrequired | string | null | Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs. |
firstNamerequired | string | |
lastNamerequired | string | null | |
companyrequired | string | null | |
vatNumberrequired | string | null | |
phonerequired | string | null | |
addressrequired | string | null | |
activerequired | boolean | |
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"contactType": "company",
"email": "[email protected]",
"billingEmail": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}400None or more than one lookup key, or a value too long.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Provide exactly one of email, externalReference or accountCode"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No matching customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/lookup?email=thandi%40example.co.za" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a customer#
/api/v1/customers/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
accountCoderequired | string | Customer account code assigned by CentraPoint. |
externalReferencerequired | string | null | Your ID for the customer. |
contactTyperequired | string | One of: |
emailrequired | string | |
billingEmailrequired | string | null | Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs. |
firstNamerequired | string | |
lastNamerequired | string | null | |
companyrequired | string | null | |
vatNumberrequired | string | null | |
phonerequired | string | null | |
addressrequired | string | null | |
activerequired | boolean | |
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"contactType": "company",
"email": "[email protected]",
"billingEmail": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access (or the feature) is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a customer#
/api/v1/customers/{id}Partial update. Omitted fields are unchanged; null clears optional fields; metadata replaces the whole map. Unknown fields are rejected. Idempotency-Key is not used (PATCH is naturally repeatable).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
externalReference | string | null | Must not be used by another customer. 1–190 chars |
email | string (email) | Stored lower-cased. max 200 chars |
firstName | string | 1–100 chars |
lastName | string | null | max 100 chars |
company | string | null | max 200 chars |
vatNumber | string | null | max 30 chars |
phone | string | null | max 30 chars |
address | string | null | max 1000 chars |
metadata | MetadataInput | null | |
active | boolean | |
contactType | string | Default One of: |
billingEmail | string (email) | null | Separate billing address. Subscription emails are sent here instead of max 320 chars |
Responses#
200Updated customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
accountCoderequired | string | Customer account code assigned by CentraPoint. |
externalReferencerequired | string | null | Your ID for the customer. |
contactTyperequired | string | One of: |
emailrequired | string | |
billingEmailrequired | string | null | Billing email: subscription emails go here when set, and it is printed on invoice and statement PDFs. |
firstNamerequired | string | |
lastNamerequired | string | null | |
companyrequired | string | null | |
vatNumberrequired | string | null | |
phonerequired | string | null | |
addressrequired | string | null | |
activerequired | boolean | |
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg2c0s7t0003cust0001abcd",
"accountCode": "CUS-00042",
"externalReference": "CRM-1001",
"contactType": "company",
"email": "[email protected]",
"billingEmail": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi",
"company": "Nkosi Trading (Pty) Ltd",
"vatNumber": "4123456789",
"phone": "+27821234567",
"address": "12 Long Street, Cape Town, 8001",
"active": true,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:00:00.000Z",
"updatedAt": "2026-09-25T08:00:00.000Z"
}400Validation failed, unknown field, or externalReference used by another customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Another customer already has that externalReference"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+27829876543",
"company": null,
"active": true
}'Send a customer portal link, or create a sign-in link#
/api/v1/customers/{id}/portal-linkDefault (no body, {} or { "email": true }): emails the customer the portal sign-in page and returns its URL (sent: true). { "email": false, "expiresInMinutes"?, "section"? }: sends nothing and returns a single-use sign-in URL (sent: false, expiresAt) that signs the customer straight in to the portal, valid 15 minutes by default (at most 1440). Create it when your signed-in user clicks through and redirect them; treat it as a secret. Not idempotent (the Idempotency-Key header is ignored).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
email | boolean |
default true |
expiresInMinutes | integer | Sign-in links only ( ≥ 1 · ≤ 1 440 · default 15 |
section | string | Sign-in links only: portal page to open after sign-in (default the overview). One of: |
Responses#
200The link was emailed (`sent: true`), or the sign-in link was created (`sent: false`).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
customerIdrequired | string | |
urlrequired | string | Emailed: the portal sign-in page. |
sentrequired | boolean |
|
expiresAt | string (date-time) | Sign-in links only: when the link stops working (it also stops once used). |
{
"object": "portal_link",
"customerId": "cmg2c0s7t0003cust0001abcd",
"url": "https://app.centrapoint.co.za/portal/acme",
"sent": true
}{
"object": "portal_link",
"customerId": "cmg2c0s7t0003cust0001abcd",
"url": "https://app.centrapoint.co.za/api/portal/auth/acme/link?token=q3Jx…&next=invoices",
"sent": false,
"expiresAt": "2026-10-01T08:10:00.000Z"
}400Unknown fields, or `expiresInMinutes` / `section` without `email: false`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}409The customer portal is not enabled (Settings → Customer portal) or not in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "portal_disabled",
"message": "The customer portal is not enabled. Turn it on under Settings > Customer portal."
}422`not_sent`: inactive customer, portal email template disabled, or the email failed (`url` included when known). `customer_inactive`: sign-in link requested for an inactive customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_sent",
"message": "The customer is inactive and cannot sign in to the portal.",
"url": "https://app.centrapoint.co.za/portal/acme"
}{
"error": "customer_inactive",
"message": "The customer is inactive and cannot sign in to the portal."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/portal-link" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": false,
"expiresInMinutes": 10,
"section": "invoices"
}'Get a customer's account standing#
/api/v1/customers/{id}/standingThe customer's account standing: ok, grace (something is due; show a banner) or locked (the grace period ended; limit the account to billing until it is resolved), why, until when, what is outstanding, and links to add a card (links.addCardUrl) and to pay the oldest outstanding invoice (links.payUrl). Calculated on every request. While the standing rules are off (Settings → Cards & standing) the status is always ok. Rules: a customer on a paid plan without a payment method gets the grace period (default 3 days) from the start of the plan; an invoice past its due date gets it from the due date; customers who existed when the rules were switched on get 14 days first. An open add-card session for the same returnUrl is reused, so polling creates no new ones.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
Query parameters#
| Field | Type | Description |
|---|---|---|
returnUrl | string (uri) | Where the add-card page returns the customer: https, on an origin allowed under Settings → API keys → Allowed return URLs. |
paidPlan | string | Overrides the paid-plan check for plans kept outside CentraPoint: One of: |
Responses#
200The customer's standing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerIdrequired | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reasonrequired | string | null | What locked the account, or what will lock it first. One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reasonsrequired | string[] | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
graceEndsAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lockedSincerequired | string (date-time) | null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lockModerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rulesEnabledrequired | boolean | The standing rules are switched on (Settings → Cards & standing). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rulesApplyFromrequired | string (date-time) | null | Customers who existed when the rules were switched on: when the rules start to apply to them. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paidPlanrequired | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasPaymentMethodrequired | boolean | A usable saved card, an active debit order mandate or a gateway card subscription. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentMethodsrequired | object | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
outstandingrequired | object | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
linksrequired | object | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
checkedAtrequired | string (date-time) |
{
"object": "customer_standing",
"customerId": "cmg2c0s7t0003cust0001abcd",
"status": "grace",
"reason": "unpaid_invoice",
"reasons": [
"unpaid_invoice"
],
"graceEndsAt": "2026-10-08T07:00:00.000Z",
"lockedSince": null,
"lockMode": "billing_only",
"rulesEnabled": true,
"rulesApplyFrom": null,
"paidPlan": true,
"hasPaymentMethod": true,
"paymentMethods": {
"cards": 1,
"defaultCard": {
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
},
"debitOrder": false,
"gatewaySubscription": false
},
"outstanding": {
"amount": 299,
"overdueAmount": 299,
"currency": "ZAR",
"invoiceIds": [
"cmg4i5n6v0001inv0001abcd"
],
"invoices": [
{
"id": "cmg4i5n6v0001inv0001abcd",
"number": "INV-000123",
"dueDate": "2026-10-05T07:00:00.000Z",
"balance": 299,
"currency": "ZAR",
"overdue": true,
"paymentPending": false,
"awaitingCollection": false
}
]
},
"links": {
"addCardUrl": "https://app.centrapoint.co.za/card/Q2x9…",
"payUrl": "https://app.centrapoint.co.za/pay/k7Rt…"
},
"checkedAt": "2026-10-06T09:00:00.000Z"
}400`paidPlan` is not true or false, or `returnUrl` is not on an allowed origin.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "paidPlan must be true or false"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/standing" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List a customer's saved cards#
/api/v1/customers/{id}/cardsThe customer's saved cards, the default first. Never the card number: brand, last four digits and expiry only.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
Query parameters#
| Field | Type | Description |
|---|---|---|
includeRemoved | string |
One of: |
Responses#
200The cards.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | Card[] | Show fields
|
{
"object": "list",
"data": [
{
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Start the hosted add-card page#
/api/v1/customers/{id}/cards/setupCreates a card setup session for the customer and returns its hosted url: redirect the customer there. They pay R1.00 by card to save it; the R1.00 is credited to the customer and taken off their next invoice. Afterwards they return to returnUrl with ?cardSetup=<session id>&status=completed|failed|expired (from the browser: confirm with GET .../cards/setup/{sessionId} or the customer.payment_method.added webhook). Needs a payment gateway that can save cards (Netcash Pay Now).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
returnUrl | string (uri) | https, on an origin allowed under Settings → API keys → Allowed return URLs. max 1000 chars |
makeDefault | boolean | Make the saved card the customer's default. default true |
expiresInMinutes | integer | ≥ 5 · ≤ 10 080 · default 1440 |
metadata | object | String map echoed on the session. |
Responses#
201The session, with its hosted URL.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
customerIdrequired | string | |
statusrequired | string | One of: |
urlrequired | string | Hosted add-card page. Redirect the customer here. |
returnUrlrequired | string | null | |
amountrequired | number | The verification amount the customer pays (credited to them). |
currencyrequired | string | |
makeDefaultrequired | boolean | |
cardIdrequired | string | null | The saved card once completed. |
failureReasonrequired | string | null | The last attempt of a pending session. One of: |
metadatarequired | object | |
expiresAtrequired | string (date-time) | |
completedAtrequired | string (date-time) | null | |
createdAtrequired | string (date-time) |
{
"object": "card_setup_session",
"id": "cmgsetup0001session0001ab",
"customerId": "cmg2c0s7t0003cust0001abcd",
"status": "pending",
"url": "https://app.centrapoint.co.za/card/Q2x9…",
"returnUrl": "https://platform.example.co.za/billing",
"amount": 1,
"currency": "ZAR",
"makeDefault": true,
"cardId": null,
"failureReason": null,
"metadata": {
"platformUserId": "42"
},
"expiresAt": "2026-10-06T08:00:00.000Z",
"completedAt": null,
"createdAt": "2026-10-05T08:00:00.000Z"
}400Unknown fields, an inactive customer, or a `returnUrl` that is not https or not on an allowed origin.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "returnUrl origin https://evil.example is not allowed - add it under Settings > API keys > Allowed return URLs"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No customer with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer not found"
}409`card_setup_unavailable`: no payment gateway that can save cards.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "card_setup_unavailable",
"message": "Saving cards needs a payment gateway that can save cards (Netcash Pay Now). Add one under Settings > Payment gateways."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/setup" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"returnUrl": "https://platform.example.co.za/billing",
"metadata": {
"platformUserId": "42"
}
}'Get an add-card session#
/api/v1/customers/{id}/cards/setup/{sessionId}pending (open; failureReason describes the last attempt: declined, cancelled or no_card_saved), completed (cardId is the saved card) or expired.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
sessionIdrequired | string | Card setup session ID. |
Responses#
200The session.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
customerIdrequired | string | |
statusrequired | string | One of: |
urlrequired | string | Hosted add-card page. Redirect the customer here. |
returnUrlrequired | string | null | |
amountrequired | number | The verification amount the customer pays (credited to them). |
currencyrequired | string | |
makeDefaultrequired | boolean | |
cardIdrequired | string | null | The saved card once completed. |
failureReasonrequired | string | null | The last attempt of a pending session. One of: |
metadatarequired | object | |
expiresAtrequired | string (date-time) | |
completedAtrequired | string (date-time) | null | |
createdAtrequired | string (date-time) |
{
"object": "card_setup_session",
"id": "cmgsetup0001session0001ab",
"customerId": "cmg2c0s7t0003cust0001abcd",
"status": "completed",
"url": "https://app.centrapoint.co.za/card/Q2x9…",
"returnUrl": "https://platform.example.co.za/billing",
"amount": 1,
"currency": "ZAR",
"makeDefault": true,
"cardId": "cmgcard00001visa4242abcd",
"failureReason": null,
"metadata": {
"platformUserId": "42"
},
"expiresAt": "2026-10-06T08:00:00.000Z",
"completedAt": "2026-10-05T08:03:00.000Z",
"createdAt": "2026-10-05T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No card setup session with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Card setup session not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/setup/cmgsetup0001session0001ab" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a saved card#
/api/v1/customers/{id}/cards/{cardId}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
cardIdrequired | string | Card ID. |
Responses#
200The card.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
customerIdrequired | string | |
brandrequired | string |
One of: |
last4required | string | |
expiryMonthrequired | integer | null | ≥ 1 · ≤ 12 |
expiryYearrequired | integer | null | |
holderNamerequired | string | null | |
isDefaultrequired | boolean | The card offered first and charged automatically. At most one per customer. |
statusrequired | string |
One of: |
expiringrequired | boolean | Active and expiring within 30 days. |
sourcerequired | string | Saved on the add-card page, or while paying ("save this card"). One of: |
createdAtrequired | string (date-time) | |
lastUsedAtrequired | string (date-time) | null | Last successful charge. |
chargeable | boolean | API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable. |
{
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No card with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Card not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Remove a saved card#
/api/v1/customers/{id}/cards/{cardId}Stops using the card (status removed). A charge of the card not yet sent to the bank is cancelled; when it was the default, the newest other usable card becomes the default. Sends customer.payment_method.removed. Not idempotent: removing it again returns 404.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
cardIdrequired | string | Card ID. |
Responses#
200The removed card.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
customerIdrequired | string | |
brandrequired | string |
One of: |
last4required | string | |
expiryMonthrequired | integer | null | ≥ 1 · ≤ 12 |
expiryYearrequired | integer | null | |
holderNamerequired | string | null | |
isDefaultrequired | boolean | The card offered first and charged automatically. At most one per customer. |
statusrequired | string |
One of: |
expiringrequired | boolean | Active and expiring within 30 days. |
sourcerequired | string | Saved on the add-card page, or while paying ("save this card"). One of: |
createdAtrequired | string (date-time) | |
lastUsedAtrequired | string (date-time) | null | Last successful charge. |
chargeable | boolean | API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable. |
{
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": false,
"status": "removed",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No card with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Card not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X DELETE "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Make a saved card the default#
/api/v1/customers/{id}/cards/{cardId}/defaultThe default card is offered first on the pay page and charged by automatic collection. Expired, failed and removed cards are refused.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
cardIdrequired | string | Card ID. |
Responses#
200The card, now the default.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
customerIdrequired | string | |
brandrequired | string |
One of: |
last4required | string | |
expiryMonthrequired | integer | null | ≥ 1 · ≤ 12 |
expiryYearrequired | integer | null | |
holderNamerequired | string | null | |
isDefaultrequired | boolean | The card offered first and charged automatically. At most one per customer. |
statusrequired | string |
One of: |
expiringrequired | boolean | Active and expiring within 30 days. |
sourcerequired | string | Saved on the add-card page, or while paying ("save this card"). One of: |
createdAtrequired | string (date-time) | |
lastUsedAtrequired | string (date-time) | null | Last successful charge. |
chargeable | boolean | API responses only (not webhooks): CentraPoint can charge this card now (active, not expired, Visa or Mastercard, and your organisation has a gateway that charges saved cards). A card can be a valid payment method without being chargeable. |
{
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
}400The card is expired or failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "This card is expired and cannot be the default"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No card with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Card not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/cmgcard00001visa4242abcd/default" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Charge a saved card#
/api/v1/customers/{id}/cards/{cardId}/chargesCharges the customer's saved card without the customer present, for example your platform's own renewal invoice. cardId may be default (the customer's default card). The bank charges the card as a card debit: the charge is created pending and completes (payment.complete) or fails (payment.failed) within about 1-3 business days; both webhooks carry your externalReference and metadata. At most one pending or successful charge per externalReference. The API key needs the cards:charge permission (Settings → API keys). Limits: 60 charges a minute per organisation and 10 a day per customer, besides the key's 120 requests a minute.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Customer ID. |
cardIdrequired | string | Card ID, or |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
amountrequired | number | Amount in ZAR, at most two decimals. > 0 · ≤ 1 000 000 |
currency | string | Only ZAR. Default ZAR. One of: |
descriptionrequired | string | What the charge is for (dashboard, receipt, your books). 1–255 chars |
externalReferencerequired | string | Your reference, e.g. your invoice number. At most one pending or successful charge per externalReference in your organisation; after a failed charge the same value may be charged again. Sent back in payment webhooks. 1–100 chars |
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, |
Responses#
201The charge, pending until the bank confirms it.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | ||||||||||||
idrequired | string | Transaction ID. | ||||||||||||
referencerequired | string | Payment reference (GET /api/v1/transactions/{reference}, payment webhooks). | ||||||||||||
statusrequired | string |
One of: | ||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | One of: | ||||||||||||
descriptionrequired | string | null | |||||||||||||
externalReferencerequired | string | |||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||
customerIdrequired | string | |||||||||||||
cardrequired | object | Show fields
| ||||||||||||
failureReasonrequired | string | null | Why it failed (e.g. the bank's unpaid reason). | ||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||
createdAtrequired | string (date-time) |
{
"object": "card_charge",
"id": "cmgchg0001charge0001abcd",
"reference": "CPA-3F9A1C7B2E4D6F80-1",
"status": "pending",
"amount": 199,
"currency": "ZAR",
"description": "Pro plan - October 2026",
"externalReference": "INV-1001",
"metadata": {
"platformInvoiceId": "1001"
},
"customerId": "cmg2c0s7t0003cust0001abcd",
"card": {
"id": "cmgcard00001visa4242abcd",
"brand": "visa",
"last4": "4242"
},
"failureReason": null,
"paidAt": null,
"createdAt": "2026-10-08T06:00:00.000Z"
}400Invalid body (amount not above zero or with more than two decimals, a currency other than ZAR, unknown fields) or an inactive customer.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403The API key lacks the `cards:charge` permission (`permission_required`), API access is not in your plan (`plan_restricted`), your account is read-only (`account_restricted`) or business verification is not approved (`compliance_required`).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "permission_required",
"message": "This API key may not charge saved cards. Allow \"Charge saved cards\" for the key under Settings > API keys."
}404No such customer or card in your organisation (removed cards included).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Customer or card not found"
}409`charge_exists`: a pending or successful charge with this externalReference exists (returned in `charge`). `no_default_card`: `default` and the customer has no default card. `card_not_chargeable`: the card is expired or failed, or not a Visa / Mastercard your gateway can charge. `card_charges_unavailable`: no gateway that charges saved cards.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "charge_exists",
"message": "A pending charge with this externalReference already exists",
"charge": {
"object": "card_charge",
"id": "cmgchg0001charge0001abcd",
"reference": "CPA-3F9A1C7B2E4D6F80-1",
"status": "pending",
"amount": 199,
"currency": "ZAR",
"description": "Pro plan - October 2026",
"externalReference": "INV-1001",
"metadata": {
"platformInvoiceId": "1001"
},
"customerId": "cmg2c0s7t0003cust0001abcd",
"card": {
"id": "cmgcard00001visa4242abcd",
"brand": "visa",
"last4": "4242"
},
"failureReason": null,
"paidAt": null,
"createdAt": "2026-10-08T06:00:00.000Z"
}
}429Too many charges: 60 a minute per organisation or 10 a day per customer (`Retry-After` says when to try again), or the key's request limit.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "rate_limited",
"message": "At most 10 saved card charges a day per customer"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/cards/default/charges" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"amount": 199,
"description": "Pro plan - October 2026",
"externalReference": "INV-1001",
"metadata": {
"platformInvoiceId": "1001"
}
}'List invoices#
/api/v1/invoicesNewest first, with keyset pagination (limit, startingAfter; the response is { data, hasMore, nextCursor }). status=draft|sent|overdue returns only invoices with nothing paid; use partially_paid for open invoices with part payments. Several statuses can be combined, comma-separated. Each invoice includes its payments.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | One or more comma-separated statuses: |
number | string | Exact invoice number, e.g. |
customerId | string | Filter by customer. |
customerExternalReference | string | Filter by the customer's externalReference. |
externalReference | string | The invoice's externalReference (exact match). |
from | string (date) | Start date (YYYY-MM-DD, SAST, inclusive) on the issue date. |
to | string (date) | End date (YYYY-MM-DD, SAST, inclusive) on the issue date. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of invoices.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Invoice[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"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"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status, bad date format or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one or more (comma-separated) of draft, sent, overdue, paid, cancelled, partially_paid"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/invoices" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create an invoice#
/api/v1/invoicesCreates an invoice with per-line VAT (201). If externalReference matches an existing invoice, that invoice is returned unchanged with 200 (the body is not applied and it is not re-sent). A pay link for the balance is created when your plan includes payment links and a gateway accepts the currency. Invoices are drafts by default. status: "sent" (or issue: true) creates the invoice issued without an email; send: true issues it and emails it. invoice.sent is sent either way. Requires the Invoicing feature.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | The customer's CentraPoint ID. Send exactly one of | ||||||||||||||||||||||||
customer | object | object | The customer, by CentraPoint ID or by your externalReference. Send exactly one of Show fields
| ||||||||||||||||||||||||
externalReference | string | Your ID for the invoice. If an invoice with this reference exists, it is returned unchanged with 200. 1–190 chars | ||||||||||||||||||||||||
currency | string | ISO 4217 code (validated). No gateway is required: invoices can be paid offline, but default "ZAR" | ||||||||||||||||||||||||
issueDate | string (date) | YYYY-MM-DD (South African time). Default today. | ||||||||||||||||||||||||
dueDate | string (date) | YYYY-MM-DD (South African time, end of day). Default: today plus your invoice due days setting. | ||||||||||||||||||||||||
periodStart | string (date) | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Omit for once-off sales. | ||||||||||||||||||||||||
periodEnd | string (date) | Last day of the billing period (YYYY-MM-DD, inclusive). | ||||||||||||||||||||||||
linesrequired | object[] | Show fields
| ||||||||||||||||||||||||
notes | string | Defaults to your invoice terms. max 4000 chars | ||||||||||||||||||||||||
taxInclusive | boolean | Line prices already include tax. Default default false | ||||||||||||||||||||||||
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
send | boolean | Default false. default false | ||||||||||||||||||||||||
status | string |
One of: default "draft" | ||||||||||||||||||||||||
issue | boolean | Same as |
Responses#
200An invoice with this externalReference already existed; returned unchanged.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"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"
}201Invoice created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"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"
}400Validation failed, invalid ISO 4217 currency, customer not found, or totals invalid.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Customer not found"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-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
}'Get an invoice#
/api/v1/invoices/{id}By ID or invoice number. Includes payments: offline payments and completed transactions linked to the invoice.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Responses#
200The invoice.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"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"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID or number in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Send an invoice#
/api/v1/invoices/{id}/sendEmails the invoice to the customer, with a pay link for the balance when possible. A draft becomes sent. Paid or cancelled invoices cannot be sent. No body is required. Always emails; to issue without an email use POST /api/v1/invoices/{id}/issue.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
object
Responses#
200The invoice after sending.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"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"
}400The invoice is in a state that does not allow this, or validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invoice is paid"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/send" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Issue an invoice without emailing#
/api/v1/invoices/{id}/issueMarks a draft invoice as issued (sent) without emailing the customer: it becomes payable, reminders and the overdue job apply, it syncs to accounting, invoice.sent is sent and a pay link is created when possible. Already issued invoices (sent, overdue, partially paid, paid) are returned unchanged; cancelled invoices return 400. No body is required.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
object
Responses#
200The issued invoice (or the unchanged invoice when it was already issued).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"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"
}400The invoice is cancelled.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invoice is cancelled"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/issue" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Cancel an invoice#
/api/v1/invoices/{id}/cancelVoids an unpaid (or partially paid) invoice and deactivates its pay links. Cancelling an already cancelled invoice returns it unchanged. Paid invoices cannot be cancelled.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
reason | string | Appended to the invoice notes. max 500 chars |
Responses#
200The cancelled invoice.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "cancelled",
"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": null,
"notes": "Payment due within 14 days.",
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:05:00.000Z",
"updatedAt": "2026-09-25T08:05:00.000Z"
}400The invoice is in a state that does not allow this, or validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Paid invoices cannot be cancelled - record a refund or credit instead"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"reason": "Order cancelled by customer"
}'Record an offline payment or allocate an existing payment#
/api/v1/invoices/{id}/paymentsTwo bodies. { amount, method, reference?, paidAt? } records money received outside CentraPoint's gateways (EFT, cash, card machine, wallet credit…). { transactionReference } allocates an existing completed CentraPoint payment that is not linked to an invoice yet (no new money): 201, or 200 when it is already allocated to this invoice; 409 already_allocated when it belongs to another invoice; 400 when it is not complete or was refunded, is in another currency or of another customer, or would overpay. The invoice becomes paid when fully paid (pay links are deactivated) or partially_paid otherwise. Always send an Idempotency-Key so a retry does not record an offline payment twice.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
InvoicePaymentCreate | InvoicePaymentAllocate
Responses#
200Allocation only: the payment was already allocated to this invoice; the invoice, unchanged.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "paid",
"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": 620,
"amountDue": 0,
"paidAt": "2026-10-02T08:15:00.000Z",
"payments": [
{
"id": "cmg2q8r4s0009ipay0001abcd",
"source": "offline",
"origin": "api",
"method": "eft",
"status": "complete",
"amount": 620,
"refundedAmount": 0,
"currency": "ZAR",
"date": "2026-10-02T08:15:00.000Z",
"reference": "FNB 2026-10-02 NKOSI",
"transactionReference": null
}
],
"payUrl": null,
"notes": "Payment due within 14 days.",
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:05:00.000Z",
"updatedAt": "2026-09-25T08:05:00.000Z"
}201Payment recorded or allocated; the updated invoice.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||
numberrequired | string | |||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||
issueDaterequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
dueDaterequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. Null for once-off sales. Subscription invoices use the billing cycle. | ||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the invoice covers (YYYY-MM-DD, inclusive), or null. | ||||||||||||||||||||||||||||||||||||
linesrequired | InvoiceLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||
taxInclusiverequired | boolean |
| ||||||||||||||||||||||||||||||||||||
subtotalrequired | number | |||||||||||||||||||||||||||||||||||||
taxAmountrequired | number | |||||||||||||||||||||||||||||||||||||
totalrequired | number | |||||||||||||||||||||||||||||||||||||
amountPaidrequired | number | |||||||||||||||||||||||||||||||||||||
amountDuerequired | number | total − amountPaid. | ||||||||||||||||||||||||||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||
paymentsrequired | InvoicePaymentEntry[] | Money received against the invoice, oldest first: offline payments and completed CentraPoint transactions. Show fields
| ||||||||||||||||||||||||||||||||||||
payUrlrequired | string (uri) | null | Hosted payment page for the outstanding balance, or null (paid/cancelled, no pay link yet, or neither a checkout gateway nor Manual EFT accepts the currency). | ||||||||||||||||||||||||||||||||||||
notesrequired | string | null | |||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "paid",
"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": 620,
"amountDue": 0,
"paidAt": "2026-10-02T08:15:00.000Z",
"payments": [
{
"id": "cmg2q8r4s0009ipay0001abcd",
"source": "offline",
"origin": "api",
"method": "eft",
"status": "complete",
"amount": 620,
"refundedAmount": 0,
"currency": "ZAR",
"date": "2026-10-02T08:15:00.000Z",
"reference": "FNB 2026-10-02 NKOSI",
"transactionReference": null
}
],
"payUrl": null,
"notes": "Payment due within 14 days.",
"metadata": {
"crmId": "0061x00000AbCdE"
},
"createdAt": "2026-09-25T08:05:00.000Z",
"updatedAt": "2026-09-25T08:05:00.000Z"
}400The invoice is in a state that does not allow this, or validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Amount exceeds the outstanding balance of 620.00"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}409`already_allocated`: the transaction is allocated to another invoice; or `idempotency_conflict`: the Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "already_allocated",
"message": "Transaction CP-20260930-7K2M9QXA is already allocated to another invoice"
}{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/invoices/cmg2i9n0v0005inv0001abcd/payments" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"transactionReference": "CP-20260930-7K2M9QXA"
}'Download an invoice PDF#
/api/v1/invoices/{id}/pdfThe branded invoice PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Invoice ID or invoice number (e.g. INV-000042). |
Responses#
200The PDF.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Content-Disposition– `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No invoice with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Invoice not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/invoices/cmg2i4n5v0004inv0001abcd/pdf" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List quotes#
/api/v1/quotesNewest first, with keyset pagination. Sent quotes past their expiry date are reported as expired.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | One of: |
customerId | string | |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of quotes.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Quote[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "sent",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of draft, sent, accepted, declined, expired, invoiced"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/quotes" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a quote#
/api/v1/quotesCreates a quote with per-line VAT (same rules as invoices). send: true creates it as sent. Emits quote.created (and quote.sent). Requires the Invoicing feature.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | Send exactly one of | ||||||||||||||||||||||||
customerExternalReference | string | Your reference of an existing customer. max 190 chars | ||||||||||||||||||||||||
lineItemsrequired | FinanceLineInput[] | Show fields
| ||||||||||||||||||||||||
currency | string | ISO 4217, default ZAR. | ||||||||||||||||||||||||
issueDate | string (date) | YYYY-MM-DD, default today. | ||||||||||||||||||||||||
expiryDate | string (date) | YYYY-MM-DD, last valid day (inclusive). Default: no expiry. | ||||||||||||||||||||||||
periodStart | string (date) | First day of the billing period the quote covers (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Copied to the invoice when the quote is converted. | ||||||||||||||||||||||||
periodEnd | string (date) | Last day of the billing period (YYYY-MM-DD, inclusive). | ||||||||||||||||||||||||
notes | string | max 4000 chars | ||||||||||||||||||||||||
taxInclusive | boolean | default false | ||||||||||||||||||||||||
send | boolean | Create it as default false |
Responses#
201Quote created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "sent",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}400Validation failed, customer not found, invalid currency, expiry before issue date, or totals invalid.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Customer not found"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/quotes" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"customerExternalReference": "CRM-1001",
"expiryDate": "2026-10-26",
"lineItems": [
{
"description": "Website redesign",
"quantity": 1,
"unitPrice": 4500
},
{
"description": "Hosting setup",
"quantity": 1,
"unitPrice": 500
}
],
"notes": "Valid for 30 days.",
"send": true
}'Get a quote#
/api/v1/quotes/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Responses#
200The quote.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "sent",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a quote#
/api/v1/quotes/{id}Edits a draft or sent quote. Omitted fields keep their value; null clears expiryDate, notes or the billing period; lineItems replaces every line. Emits quote.updated.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | Send exactly one of | ||||||||||||||||||||||||
customerExternalReference | string | Your reference of an existing customer. max 190 chars | ||||||||||||||||||||||||
lineItems | FinanceLineInput[] | Show fields
| ||||||||||||||||||||||||
currency | string | ISO 4217, default ZAR. | ||||||||||||||||||||||||
issueDate | string (date) | YYYY-MM-DD, default today. | ||||||||||||||||||||||||
expiryDate | string (date) | null | |||||||||||||||||||||||||
periodStart | string (date) | null | YYYY-MM-DD, inclusive. | ||||||||||||||||||||||||
periodEnd | string (date) | null | YYYY-MM-DD, inclusive. | ||||||||||||||||||||||||
notes | string | null | max 4000 chars | ||||||||||||||||||||||||
taxInclusive | boolean | default false |
Responses#
200The updated quote.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "sent",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}400Validation failed, or the quote is not draft or sent.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A accepted quote cannot be edited"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"expiryDate": "2026-11-15",
"notes": "Valid until 15 November."
}'Delete a draft quote#
/api/v1/quotes/{id}Permanently deletes a draft quote. Other quotes return 400 (decline them instead). No webhook is sent.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Responses#
200Deleted.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
objectrequired | string | One of: |
idrequired | string | |
numberrequired | string | |
deletedrequired | boolean | One of: |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"deleted": true
}400The quote is not a draft.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Only draft quotes can be deleted - decline it instead"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X DELETE "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Mark a quote sent#
/api/v1/quotes/{id}/sendMarks a draft or expired quote sent (an already sent quote is returned unchanged). CentraPoint does not email quotes; share the PDF. Emits quote.sent.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The updated quote.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "sent",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}400The status change is not allowed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A invoiced quote cannot be marked sent"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/send" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Mark a quote accepted#
/api/v1/quotes/{id}/acceptMarks a draft, sent or expired quote accepted. Emits quote.accepted.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The updated quote.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "accepted",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": "2026-09-29T11:02:09.000Z",
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}400The status change is not allowed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A invoiced quote cannot be marked accepted"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/accept" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Mark a quote declined#
/api/v1/quotes/{id}/declineMarks a draft, sent, expired or accepted quote declined. Emits quote.declined.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The updated quote.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential quote number, e.g. | |||||||||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
expiryDaterequired | string (date-time) | null | End of the last valid day (SAST); null for no expiry. | |||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the quote covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
notesrequired | string | null | ||||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | The invoice the quote was converted into. Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
sentAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
acceptedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
declinedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "declined",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": null,
"declinedAt": "2026-09-29T11:02:09.000Z",
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
}400The status change is not allowed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A invoiced quote cannot be marked declined"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/decline" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Convert a quote to an invoice#
/api/v1/quotes/{id}/convertCreates a draft invoice from the quote's lines (due in dueDays), marks the quote invoiced and links them. A pay link is created when your plan includes payment links and a gateway accepts the currency. Emits quote.invoiced and invoice.created.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
dueDays | integer | Default: your invoice due-days setting. ≥ 0 · ≤ 365 |
Responses#
201The invoiced quote and the new invoice.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
quoterequired | Quote | Returned by every quote endpoint and sent as Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoicerequired | Invoice | Show fields
|
{
"quote": {
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "invoiced",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg3i2j3k0004inv0061abcd",
"number": "INV-000061",
"status": "draft",
"externalReference": null
},
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": "2026-09-27T08:00:00.000Z",
"acceptedAt": "2026-09-29T11:05:00.000Z",
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T08:00:00.000Z"
},
"invoice": {
"id": "cmg3i2j3k0004inv0061abcd",
"number": "INV-000061",
"status": "draft",
"externalReference": null,
"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"
}
}400The quote is declined or already invoiced.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "This quote has already been invoiced"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/convert" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"dueDays": 14
}'Download a quote PDF#
/api/v1/quotes/{id}/pdfThe branded quote PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Quote ID or quote number. |
Responses#
200The PDF.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Content-Disposition– `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No quote with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Quote not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/quotes/cmg3q1a2b0001quo0001abcd/pdf" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List credit notes#
/api/v1/credit-notesNewest first, with keyset pagination.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | One of: |
customerId | string | |
invoiceId | string | |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of credit notes.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | CreditNote[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "issued",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 100,
"amountRefunded": 0,
"balance": 130,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [
{
"at": "2026-09-27T09:20:00.000Z",
"kind": "applied",
"amount": 100,
"ref": "INV-000051"
}
],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of draft, issued, applied, refunded, void"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/credit-notes" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a credit note#
/api/v1/credit-notesCreates a credit note, optionally against an invoice (customer, currency and tax rate then come from the invoice; credit notes on one invoice can't exceed its total). issue: true issues it immediately. Emits credit_note.created (and credit_note.issued). Requires the Invoicing feature.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | |||||||||||||||||||||||||
customerExternalReference | string | max 190 chars | ||||||||||||||||||||||||
invoiceId | string | Credit against this invoice: its customer, currency and tax rate are used. | ||||||||||||||||||||||||
lineItemsrequired | FinanceLineInput[] | Show fields
| ||||||||||||||||||||||||
currency | string | ISO 4217, default ZAR (the invoice's when invoiceId is sent). | ||||||||||||||||||||||||
taxInclusive | boolean | default false | ||||||||||||||||||||||||
periodStart | string (date) | First day of the period being credited (YYYY-MM-DD, inclusive calendar date). Send both or neither; periodEnd must be on or after periodStart. Default: the invoice's period when | ||||||||||||||||||||||||
periodEnd | string (date) | Last day of the billing period (YYYY-MM-DD, inclusive). | ||||||||||||||||||||||||
reason | string | max 1000 chars | ||||||||||||||||||||||||
notes | string | max 4000 chars | ||||||||||||||||||||||||
issue | boolean | Issue it immediately. default false |
Responses#
201Credit note created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "issued",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 0,
"amountRefunded": 0,
"balance": 230,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:10:00.000Z"
}400Validation failed; customer or invoice not found; the invoice belongs to another customer; credit above the invoice total.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Credit notes cannot exceed the invoice total of 620.00"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"invoiceId": "cmg2i9n0v0005inv0001abcd",
"reason": "Hosting downtime 12-14 September",
"lineItems": [
{
"description": "Service credit - downtime",
"quantity": 1,
"unitPrice": 200
}
],
"issue": true
}'Get a credit note#
/api/v1/credit-notes/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Responses#
200The credit note.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "issued",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 100,
"amountRefunded": 0,
"balance": 130,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [
{
"at": "2026-09-27T09:20:00.000Z",
"kind": "applied",
"amount": 100,
"ref": "INV-000051"
}
],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Issue a credit note#
/api/v1/credit-notes/{id}/issueDraft → issued, so its credit can be used. Emits credit_note.issued.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The issued credit note.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "issued",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 100,
"amountRefunded": 0,
"balance": 130,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [
{
"at": "2026-09-27T09:20:00.000Z",
"kind": "applied",
"amount": 100,
"ref": "INV-000051"
}
],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}400Not a draft.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Only draft credit notes can be issued"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/issue" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Void a credit note#
/api/v1/credit-notes/{id}/voidVoids an unused draft or issued credit note (a void one is returned unchanged). The reason is added to the notes. Emits credit_note.voided.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
reason | string | max 500 chars |
Responses#
200The void credit note.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "void",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 0,
"amountRefunded": 0,
"balance": 230,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": "2026-09-27T09:30:00.000Z",
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}400The credit note has been used.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "This credit note has been used - it cannot be voided"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/void" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"reason": "Issued in error"
}'Apply credit to an invoice#
/api/v1/credit-notes/{id}/applyRecords an invoice payment (method credit_note) on an unpaid invoice of the same customer and currency. Emits credit_note.applied (and invoice.paid / invoice.partially_paid). Always send an Idempotency-Key.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
invoiceIdrequired | string | Unpaid invoice of the same customer and currency. |
amountrequired | number | > 0 |
Responses#
200The updated credit note.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "issued",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 100,
"amountRefunded": 0,
"balance": 130,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [
{
"at": "2026-09-27T09:20:00.000Z",
"kind": "applied",
"amount": 100,
"ref": "INV-000051"
}
],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}400Not issued, amount above the balance, or invoice not found / another customer / another currency.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "The credit balance is 130.00"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/apply" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"invoiceId": "cmg2i9n0v0005inv0051abcd",
"amount": 100
}'Pay credit back#
/api/v1/credit-notes/{id}/refundPays credit back: payment records a refund on one of the customer's completed payments (process it in the gateway's portal); payout schedules a Netcash payout to the customer's bank account (ZAR); manual records a pay-back done outside CentraPoint. Emits credit_note.refunded. Always send an Idempotency-Key.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
object | object | object
Responses#
200The updated credit note.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | |||||||||||||||||||||||||||
idrequired | string | ||||||||||||||||||||||||||||
numberrequired | string | Sequential number, e.g. | |||||||||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||||||||
issueDaterequired | string (date-time) | ||||||||||||||||||||||||||||
periodStartrequired | string (date) | null | First day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
periodEndrequired | string (date) | null | Last day of the billing period the credit note covers (YYYY-MM-DD, inclusive), or null. | |||||||||||||||||||||||||||
reasonrequired | string | null | ||||||||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||||||||
taxInclusiverequired | boolean | ||||||||||||||||||||||||||||
subtotalrequired | number | ||||||||||||||||||||||||||||
taxAmountrequired | number | ||||||||||||||||||||||||||||
totalrequired | number | ||||||||||||||||||||||||||||
amountAppliedrequired | number | Applied to invoices. | |||||||||||||||||||||||||||
amountRefundedrequired | number | Paid back, including scheduled payouts (released if the payout is cancelled or fails). | |||||||||||||||||||||||||||
balancerequired | number | total − amountApplied − amountRefunded. | |||||||||||||||||||||||||||
customerrequired | object | null | Show fields
| |||||||||||||||||||||||||||
invoicerequired | object | null | Show fields
| |||||||||||||||||||||||||||
lineItemsrequired | FinanceLine[] | Show fields
| |||||||||||||||||||||||||||
historyrequired | object[] | Show fields
| |||||||||||||||||||||||||||
refundsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
payoutsrequired | object[] | Show fields
| |||||||||||||||||||||||||||
issuedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
voidedAtrequired | string (date-time) | null | ||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "applied",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 100,
"amountRefunded": 130,
"balance": 0,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [
{
"at": "2026-09-27T09:20:00.000Z",
"kind": "applied",
"amount": 100,
"ref": "INV-000051"
},
{
"at": "2026-09-30T10:00:00.000Z",
"kind": "manual",
"amount": 130,
"ref": "FNB 2026-09-30 NKOSI",
"note": "eft"
}
],
"refunds": [],
"payouts": [],
"issuedAt": "2026-09-27T09:10:00.000Z",
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:20:00.000Z"
}400Not issued; amount above the balance; payment not found or not refundable; invalid bank details; no payout gateway; non-ZAR payout; action date in the past.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Payment not found"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or invoicing, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/refund" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"method": "payout",
"amount": 130,
"actionDate": "2026-10-01",
"bank": {
"accountHolder": "T Nkosi",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current",
"bankName": "FNB"
},
"beneficiaryEmail": "[email protected]"
}'Download a credit note PDF#
/api/v1/credit-notes/{id}/pdfThe branded credit note PDF (application/pdf, sent as an attachment, Cache-Control: private, no-store). Requires Invoicing in your plan.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Credit note ID or number. |
Responses#
200The PDF.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Content-Disposition– `attachment; filename="…"`
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No credit note with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Credit note not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/credit-notes/cmg3c7d8e0002crn0001abcd/pdf" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List subscriptions#
/api/v1/subscriptionsGateway-managed subscriptions started by recurring payment links, newest first.
Query parameters#
| Field | Type | Description |
|---|---|---|
externalReference | string | The payment link's externalReference. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Subscriptions.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Subscription[] | Show fields
|
{
"data": [
{
"id": "cmg2s5b8k0007sub0001abcd",
"status": "active",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access (or the feature) is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a subscription#
/api/v1/subscriptions/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The subscription.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
statusrequired | string | One of: | ||||||||||||||||||||||||
frequencyrequired | string | null | One of: | ||||||||||||||||||||||||
amountrequired | number | null | Amount of each collection. | ||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||
gatewayrequired | string | Gateway that bills the subscription, e.g. | ||||||||||||||||||||||||
paymentLinkIdrequired | string | null | The recurring payment link that started it. | ||||||||||||||||||||||||
externalReferencerequired | string | null | That link's externalReference. | ||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||
capabilities | GatewaySubscriptionCapabilities | What the gateway supports for this subscription (GET /subscriptions/{id} and update responses). Show fields
| ||||||||||||||||||||||||
replacementLinkId | string | null | Checkout link emailed to replace this subscription (new amount / re-authorised card). |
{
"id": "cmg2s5b8k0007sub0001abcd",
"status": "active",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access (or the feature) is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Pause a subscription#
/api/v1/subscriptions/{id}/pausePauses future collections at the gateway and sends subscription.paused. Allowed from active. Supported on gateways that can pause subscriptions (capabilities.pause), e.g. PayFast, Netcash Pay Now. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The subscription (status `paused`).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
statusrequired | string | One of: | ||||||||||||||||||||||||
frequencyrequired | string | null | One of: | ||||||||||||||||||||||||
amountrequired | number | null | Amount of each collection. | ||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||
gatewayrequired | string | Gateway that bills the subscription, e.g. | ||||||||||||||||||||||||
paymentLinkIdrequired | string | null | The recurring payment link that started it. | ||||||||||||||||||||||||
externalReferencerequired | string | null | That link's externalReference. | ||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||
capabilities | GatewaySubscriptionCapabilities | What the gateway supports for this subscription (GET /subscriptions/{id} and update responses). Show fields
| ||||||||||||||||||||||||
replacementLinkId | string | null | Checkout link emailed to replace this subscription (new amount / re-authorised card). |
{
"id": "cmg2s5b8k0007sub0001abcd",
"status": "paused",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`invalid_state`: not allowed from the current status. `unsupported`: the subscription's gateway can't do this, e.g. Netcash Pay Now subscriptions can only be cancelled.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_state",
"message": "Subscription is cancelled"
}{
"error": "unsupported",
"message": "Netcash Pay Now does not support pausing subscriptions"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}502The gateway rejected or failed the request. Nothing changed; retry later.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "gateway_error",
"message": "The payment gateway did not accept the request (pausing). Please try again."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/pause" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Resume a subscription#
/api/v1/subscriptions/{id}/resumeResumes a paused subscription at the gateway and sends subscription.resumed. Allowed from paused. Supported on gateways that can pause subscriptions (capabilities.resume), e.g. PayFast, Netcash Pay Now. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The subscription (status `active`).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
statusrequired | string | One of: | ||||||||||||||||||||||||
frequencyrequired | string | null | One of: | ||||||||||||||||||||||||
amountrequired | number | null | Amount of each collection. | ||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||
gatewayrequired | string | Gateway that bills the subscription, e.g. | ||||||||||||||||||||||||
paymentLinkIdrequired | string | null | The recurring payment link that started it. | ||||||||||||||||||||||||
externalReferencerequired | string | null | That link's externalReference. | ||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||
capabilities | GatewaySubscriptionCapabilities | What the gateway supports for this subscription (GET /subscriptions/{id} and update responses). Show fields
| ||||||||||||||||||||||||
replacementLinkId | string | null | Checkout link emailed to replace this subscription (new amount / re-authorised card). |
{
"id": "cmg2s5b8k0007sub0001abcd",
"status": "active",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`invalid_state`: not allowed from the current status. `unsupported`: the subscription's gateway can't do this, e.g. Netcash Pay Now subscriptions can only be cancelled.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_state",
"message": "Subscription is cancelled"
}{
"error": "unsupported",
"message": "Netcash Pay Now does not support resuming subscriptions"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}502The gateway rejected or failed the request. Nothing changed; retry later.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "gateway_error",
"message": "The payment gateway did not accept the request (resuming). Please try again."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/resume" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Cancel a subscription#
/api/v1/subscriptions/{id}/cancelStops future collections at the gateway and sends subscription.cancelled. Allowed from active or paused. Repeating a call that already took effect returns 200 with the subscription unchanged (the Idempotency-Key header is not used). An invalid transition returns 409 invalid_state and nothing changes. No body is required.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The cancelled subscription.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
statusrequired | string | One of: | ||||||||||||||||||||||||
frequencyrequired | string | null | One of: | ||||||||||||||||||||||||
amountrequired | number | null | Amount of each collection. | ||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||
gatewayrequired | string | Gateway that bills the subscription, e.g. | ||||||||||||||||||||||||
paymentLinkIdrequired | string | null | The recurring payment link that started it. | ||||||||||||||||||||||||
externalReferencerequired | string | null | That link's externalReference. | ||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||
capabilities | GatewaySubscriptionCapabilities | What the gateway supports for this subscription (GET /subscriptions/{id} and update responses). Show fields
| ||||||||||||||||||||||||
replacementLinkId | string | null | Checkout link emailed to replace this subscription (new amount / re-authorised card). |
{
"id": "cmg2s5b8k0007sub0001abcd",
"status": "cancelled",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Account is read-only (suspended, cancelled or trial ended), or a plan feature/quota is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`invalid_state`: not allowed from the current status. `unsupported`: the gateway can't cancel through CentraPoint.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_state",
"message": "Subscription is cancelled"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}502The gateway rejected or failed the request. Nothing changed; retry later.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "gateway_error",
"message": "The payment gateway did not accept the cancellation. Please try again."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/cmg2s5b8k0007sub0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List packages#
/api/v1/packagesSubscription packages with their plans, in sort order. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Query parameters#
| Field | Type | Description |
|---|---|---|
enabled | string |
One of: |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Packages.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Package[] | Show fields
|
{
"data": [
{
"id": "cmg4p1a2b0001pkg0001abcd",
"object": "package",
"name": "Acme Cloud",
"description": "Hosted project management",
"enabled": true,
"sortOrder": 0,
"defaultProviderId": "cmg1p0v1d0001prov0001abcd",
"plans": [
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
],
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/packages" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a package#
/api/v1/packagesCreates a package, optionally with up to 20 plans. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namerequired | string | 1–120 chars | |||||||||||||||||||||||||||||||||||||||||||||||||||
description | string | null | max 2000 chars | |||||||||||||||||||||||||||||||||||||||||||||||||||
enabled | boolean | default true | |||||||||||||||||||||||||||||||||||||||||||||||||||
sortOrder | integer | ≥ -10000 · ≤ 10 000 | |||||||||||||||||||||||||||||||||||||||||||||||||||
defaultProviderId | string | null | One of your payment providers. | |||||||||||||||||||||||||||||||||||||||||||||||||||
plans | PlanCreate[] | Plans to create with the package. Show fields
|
Responses#
201The new package with its plans.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sortOrderrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultProviderIdrequired | string | null | Gateway used for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
plans | Plan[] | Sorted by sortOrder, then price. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0001pkg0001abcd",
"object": "package",
"name": "Acme Cloud",
"description": "Hosted project management",
"enabled": true,
"sortOrder": 0,
"defaultProviderId": "cmg1p0v1d0001prov0001abcd",
"plans": [
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
],
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed, e.g. unknown provider, invalid currency, or a call-to-action plan without a URL.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Payment provider not found"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}409Idempotency-Key reused with a different body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/packages" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Cloud",
"description": "Hosted project management",
"plans": [
{
"name": "Pro",
"frequency": "monthly",
"amount": 499,
"trialDays": 14,
"features": [
"Unlimited projects",
"Priority support"
]
}
]
}'Get a package#
/api/v1/packages/{id}The package with all its plans (enabled and disabled). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The package.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sortOrderrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultProviderIdrequired | string | null | Gateway used for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
plans | Plan[] | Sorted by sortOrder, then price. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0001pkg0001abcd",
"object": "package",
"name": "Acme Cloud",
"description": "Hosted project management",
"enabled": true,
"sortOrder": 0,
"defaultProviderId": "cmg1p0v1d0001prov0001abcd",
"plans": [
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
],
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}404No package with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Package not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a package#
/api/v1/packages/{id}Partial update of name, description, enabled, sortOrder and defaultProviderId. Unknown fields are rejected. Idempotency-Key is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
name | string | 1–120 chars |
description | string | null | max 2000 chars |
enabled | boolean | default true |
sortOrder | integer | ≥ -10000 · ≤ 10 000 |
defaultProviderId | string | null | One of your payment providers. |
Responses#
200The updated package.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sortOrderrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultProviderIdrequired | string | null | Gateway used for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
plans | Plan[] | Sorted by sortOrder, then price. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0001pkg0001abcd",
"object": "package",
"name": "Acme Cloud",
"description": "Hosted project management",
"enabled": true,
"sortOrder": 0,
"defaultProviderId": "cmg1p0v1d0001prov0001abcd",
"plans": [
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
],
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No package with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Package not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Project management for teams",
"sortOrder": 1
}'Disable a package#
/api/v1/packages/{id}Disables the package (enabled: false) so it can't be subscribed to. Nothing is deleted and existing subscriptions keep billing. Re-enable it with PATCH.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The disabled package.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
descriptionrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enabledrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sortOrderrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultProviderIdrequired | string | null | Gateway used for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
plans | Plan[] | Sorted by sortOrder, then price. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0001pkg0001abcd",
"object": "package",
"name": "Acme Cloud",
"description": "Hosted project management",
"enabled": false,
"sortOrder": 0,
"defaultProviderId": "cmg1p0v1d0001prov0001abcd",
"plans": [
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
],
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No package with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Package not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X DELETE "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Add a plan to a package#
/api/v1/packages/{id}/plansCreates a plan in the package. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
namerequired | string | 1–120 chars |
code | string | null | Your key for the plan, e.g. max 100 chars |
description | string | null | max 2000 chars |
features | string[] | |
hasCallToAction | boolean | Requires |
callToActionUrl | string | null | http(s) URL. max 1000 chars |
hasContactUs | boolean | |
enabled | boolean | default true |
frequencyrequired | string | One of: |
amountrequired | number | 0 is allowed: free plans activate without a payment. ≥ 0 · ≤ 100 000 000 |
setupFee | number | ≥ 0 · ≤ 100 000 000 |
currency | string | ISO 4217 code; default ZAR. |
trialDays | integer | ≥ 0 · ≤ 730 |
billingCycles | integer | null | ≥ 1 · ≤ 1 000 |
providerIds | string[] | IDs of your payment providers (Settings → Payment providers). |
sortOrder | integer | ≥ -10000 · ≤ 10 000 |
Responses#
201The new plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
packageIdrequired | string | |
coderequired | string | null | Your key for the plan, e.g. max 100 chars |
namerequired | string | |
descriptionrequired | string | null | |
featuresrequired | string[] | Feature bullet points shown on checkout pages and in the customer portal. |
hasCallToActionrequired | boolean | The plan is shown with a button to |
callToActionUrlrequired | string | null | |
hasContactUsrequired | boolean | Show a “Contact us” option for the plan. |
enabledrequired | boolean | Disabled plans can't be subscribed to; existing subscriptions keep billing. |
frequencyrequired | string | One of: |
amountrequired | number | Price per billing period (per unit of quantity). |
setupFeerequired | number | One-off fee added to the first charge (invoiced separately for debit orders). |
currencyrequired | string | |
trialDaysrequired | integer | Free trial length for new subscriptions; 0 = no trial. |
billingCyclesrequired | integer | null | Fixed number of billing cycles; |
providerIdsrequired | string[] | Gateways customers may pay this plan with; empty = any enabled gateway. |
sortOrderrequired | integer | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0003pln0002abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Team (annual)",
"description": null,
"features": [
"Up to 25 users"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "annually",
"amount": 4990,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 0,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "currency must be a 3-letter ISO code"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No package with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Package not found"
}409Idempotency-Key reused with a different body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/packages/cmg4p1a2b0001pkg0001abcd/plans" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"name": "Team (annual)",
"frequency": "annually",
"amount": 4990,
"setupFee": 0,
"trialDays": 0,
"features": [
"Up to 25 users"
]
}'List plans (find one by code)#
/api/v1/plansPlans across your packages in sort order. code finds the plan with your code (at most one). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Query parameters#
| Field | Type | Description |
|---|---|---|
code | string | Exact plan code. |
packageId | string | |
enabled | string | One of: |
limit | integer | 1-100, default 50. ≥ 1 · ≤ 100 · default 50 |
Responses#
200Plans.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Plan[] | Show fields
|
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/plans?code=acmehosting%3Apro%3Amonthly" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a plan#
/api/v1/plans/{id}One plan. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
packageIdrequired | string | |
coderequired | string | null | Your key for the plan, e.g. max 100 chars |
namerequired | string | |
descriptionrequired | string | null | |
featuresrequired | string[] | Feature bullet points shown on checkout pages and in the customer portal. |
hasCallToActionrequired | boolean | The plan is shown with a button to |
callToActionUrlrequired | string | null | |
hasContactUsrequired | boolean | Show a “Contact us” option for the plan. |
enabledrequired | boolean | Disabled plans can't be subscribed to; existing subscriptions keep billing. |
frequencyrequired | string | One of: |
amountrequired | number | Price per billing period (per unit of quantity). |
setupFeerequired | number | One-off fee added to the first charge (invoiced separately for debit orders). |
currencyrequired | string | |
trialDaysrequired | integer | Free trial length for new subscriptions; 0 = no trial. |
billingCyclesrequired | integer | null | Fixed number of billing cycles; |
providerIdsrequired | string[] | Gateways customers may pay this plan with; empty = any enabled gateway. |
sortOrderrequired | integer | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 499,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z",
"code": null
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}404No plan with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Plan not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/plans/cmg4p1a2b0002pln0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a plan#
/api/v1/plans/{id}Partial update. Price and frequency changes apply to new subscriptions only: existing subscriptions keep their price until they change plan. enabled: false hides the plan from checkout. Idempotency-Key is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
name | string | 1–120 chars |
code | string | null | Your key for the plan, e.g. max 100 chars |
description | string | null | max 2000 chars |
features | string[] | |
hasCallToAction | boolean | Requires |
callToActionUrl | string | null | http(s) URL. max 1000 chars |
hasContactUs | boolean | |
enabled | boolean | default true |
frequency | string | One of: |
amount | number | 0 is allowed: free plans activate without a payment. ≥ 0 · ≤ 100 000 000 |
setupFee | number | ≥ 0 · ≤ 100 000 000 |
currency | string | ISO 4217 code; default ZAR. |
trialDays | integer | ≥ 0 · ≤ 730 |
billingCycles | integer | null | ≥ 1 · ≤ 1 000 |
providerIds | string[] | IDs of your payment providers (Settings → Payment providers). |
sortOrder | integer | ≥ -10000 · ≤ 10 000 |
Responses#
200The updated plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
packageIdrequired | string | |
coderequired | string | null | Your key for the plan, e.g. max 100 chars |
namerequired | string | |
descriptionrequired | string | null | |
featuresrequired | string[] | Feature bullet points shown on checkout pages and in the customer portal. |
hasCallToActionrequired | boolean | The plan is shown with a button to |
callToActionUrlrequired | string | null | |
hasContactUsrequired | boolean | Show a “Contact us” option for the plan. |
enabledrequired | boolean | Disabled plans can't be subscribed to; existing subscriptions keep billing. |
frequencyrequired | string | One of: |
amountrequired | number | Price per billing period (per unit of quantity). |
setupFeerequired | number | One-off fee added to the first charge (invoiced separately for debit orders). |
currencyrequired | string | |
trialDaysrequired | integer | Free trial length for new subscriptions; 0 = no trial. |
billingCyclesrequired | integer | null | Fixed number of billing cycles; |
providerIdsrequired | string[] | Gateways customers may pay this plan with; empty = any enabled gateway. |
sortOrderrequired | integer | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4p1a2b0002pln0001abcd",
"object": "plan",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"name": "Pro",
"description": "For growing teams",
"features": [
"Unlimited projects",
"Priority support",
"SSO"
],
"hasCallToAction": false,
"callToActionUrl": null,
"hasContactUs": false,
"enabled": true,
"frequency": "monthly",
"amount": 549,
"setupFee": 0,
"currency": "ZAR",
"trialDays": 14,
"billingCycles": null,
"providerIds": [],
"sortOrder": 1,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No plan with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Plan not found"
}409`plan_code_taken`: another plan already has that `code`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/plans/cmg4p1a2b0002pln0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 549,
"features": [
"Unlimited projects",
"Priority support",
"SSO"
]
}'List customer subscriptions#
/api/v1/customer-subscriptionsNewest first, keyset paginated (limit, startingAfter -> hasMore, nextCursor). The response still has data as before. Requires the REST API and Recurring billing in your plan.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | Status, or a comma-separated list (e.g. |
collectionMethod | string | Collection method, or a comma-separated list (e.g. |
planId | string | |
packageId | string | |
customerId | string | |
customerExternalReference | string | Your id of the customer (Customer.externalReference). |
externalReference | string | Exact match on your subscription ID. |
nextBillingFrom | string (date) | Next billing on or after (YYYY-MM-DD, SAST). |
nextBillingTo | string (date) | Next billing on or before (YYYY-MM-DD, SAST). |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200Subscriptions.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | CustomerSubscription[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null |
{
"data": [
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of incomplete, trialing, active, past_due, paused, cancelled, expired"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Subscribe a customer to a plan#
/api/v1/customer-subscriptionsCreates a subscription (201). With a trial it starts trialing; otherwise incomplete until the first payment (setup fee + first period) completes, then active. A zero first charge activates at once. payment says what is due now and where the customer pays (payUrl). With an externalReference that already exists, the existing subscription is returned with 200 and its current payment state. Unless one side is an external (mirror) subscription and the other is not, or the existing one belongs to another customer: then 409 external_reference_conflict. Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise). collectionMethod: external records a subscription your platform bills (mirror import): nothing is charged, emailed or sent as a webhook, payment.due is false and collectedByCentraPoint is false. dryRun: true validates the same way and answers 200 with CustomerSubscriptionDryRun without writing anything. The externalReference is unique per organisation, also for two requests at the same time (the second gets 200 and the first one's subscription).
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | ||||||||||||||||||||||
customer | object | object | Show fields
| |||||||||||||||||||||
planId | string | The plan id (or send | |||||||||||||||||||||
plan | string | Instead of max 190 chars | |||||||||||||||||||||
collectionMethodrequired | string |
One of: | |||||||||||||||||||||
providerId | string | Gateway or Netcash provider. Default: the package's default provider (gateway) or the mandate's (debit order). | |||||||||||||||||||||
quantity | integer | ≥ 1 · ≤ 10 000 · default 1 | |||||||||||||||||||||
couponCode | string | Needs Coupons in your plan; validated for the plan and customer. 1–50 chars | |||||||||||||||||||||
trial | boolean |
default true | |||||||||||||||||||||
trialDays | integer | Overrides the plan's trial length. ≥ 0 · ≤ 730 | |||||||||||||||||||||
mandateId | string |
| |||||||||||||||||||||
externalReference | string | Your ID, unique per organisation (also for requests at the same time). Creating again with the same value returns the existing subscription (200, 1–190 chars | |||||||||||||||||||||
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
sendEmail | boolean | Email the first invoice / payment request / trial confirmation. Never sent for default true | |||||||||||||||||||||
couponId | string | Coupon by id (instead of | |||||||||||||||||||||
startDate | string |
| |||||||||||||||||||||
paidThrough | string |
| |||||||||||||||||||||
billingAnchorDay | integer | Renewals fall on this day of the month; the first period is shortened to it and pro-rated. Monthly and longer plans; not for debit orders. ≥ 1 · ≤ 31 | |||||||||||||||||||||
items | SubscriptionItemInput[] | Add-ons (e.g. Show fields
| |||||||||||||||||||||
status | string |
One of: | |||||||||||||||||||||
currentPeriodStart | string |
| |||||||||||||||||||||
trialEnd | string |
| |||||||||||||||||||||
cancelAtPeriodEnd | boolean |
| |||||||||||||||||||||
dryRun | boolean | Validate and preview only: 200 default false |
Responses#
200A subscription with this externalReference already exists: returned unchanged with `created: false` and its current payment state. Or, with `dryRun: true`, the dry-run result.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
CustomerSubscriptionCreated | CustomerSubscriptionDryRun
201Created (`created: true`). For a trial or an external subscription nothing is due.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | boolean | true (201) for a new subscription, false (200) when one with this externalReference existed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentrequired | SubscriptionStartPayment | What is due now and how the customer pays it. Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z",
"payment": {
"due": false,
"amount": 0,
"currency": "ZAR",
"method": "none",
"payUrl": null,
"invoiceId": null,
"paymentLinkId": null,
"transactionId": null
},
"created": true
}400Validation failed: customer/plan/mandate/provider not found, inactive customer, disabled plan, invalid coupon, unsupported collection method for the plan, etc.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "This plan is not available"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403`plan_restricted`: no REST API or Recurring billing. `plan_limit`: the collection method needs Invoicing or Debit orders, which your plan lacks. `account_restricted`: the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_limit",
"message": "Debit orders is not included in the Growth plan. Upgrade under Settings > Billing."
}409`idempotency_conflict`: Idempotency-Key reused with a different body. `external_reference_conflict`: the `externalReference` belongs to another customer's subscription, or one of the two is an external (mirror) subscription and the other is not (a mirror of a subscription CentraPoint bills, or a create meant to let CentraPoint bill a mirrored one). `external_imports_unavailable`: `collectionMethod: external` (also a dry run) for a short time while CentraPoint is being updated (`GET /api/v1/me` says `capabilities.externalSubscriptions: false`); nothing was written, try again later.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}{
"error": "external_reference_conflict",
"message": "externalReference acmehosting-sub:1042 belongs to a subscription with collectionMethod external, not invoice. To let CentraPoint bill it, cancel that record and create the new subscription with its own externalReference."
}{
"error": "external_imports_unavailable",
"message": "CentraPoint is being updated, so it does not accept subscriptions your platform bills (collectionMethod external) now. Nothing was written: try again later (GET /api/v1/me says capabilities.externalSubscriptions: true once it does)."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"externalReference": "acmehosting:user:1042"
},
"plan": "acmehosting:pro:monthly",
"collectionMethod": "external",
"paidThrough": "2026-10-31",
"externalReference": "acmehosting-sub:1042",
"sendEmail": false,
"dryRun": true
}'Get a customer subscription#
/api/v1/customer-subscriptions/{id}Add ?include=events for the timeline (latest 100 events). Requires the REST API and Recurring billing in your plan (403 plan_restricted otherwise).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Query parameters#
| Field | Type | Description |
|---|---|---|
include | string |
One of: |
Responses#
200The subscription.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "Recurring billing is not included in your plan"
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a customer subscription#
/api/v1/customer-subscriptions/{id}Changes metadata, externalReference or nextBillingAt. Sends subscription.updated. Unknown fields are rejected. Idempotency-Key is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
metadata | MetadataInput | null | Replaces the whole map; |
externalReference | string | null | Must not belong to another subscription. An max 190 chars |
nextBillingAt | string (date-time) | Next renewal / charge. For card subscriptions the gateway bills itself, only where the gateway can move the date (PayFast). |
billingAnchorDay | integer | null | Day of month later renewals fall on; ≥ 1 · ≤ 31 |
Responses#
200The updated subscription.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-15T06:00:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-15T06:00:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Debit order dates follow the mandate's debit day - edit the mandate instead"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`external_subscription`: `nextBillingAt` / `billingAnchorDay` on a subscription your platform bills (use sync-period), or changing or removing its `externalReference`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nextBillingAt": "2026-10-15T08:00:00+02:00"
}'Pause a customer subscription#
/api/v1/customer-subscriptions/{id}/pauseStops billing until resumed. Allowed from active or past_due; pausing a paused subscription returns it unchanged. Linked debit order mandates are paused too; gateway-billed subscriptions are paused at the gateway first (PayFast, Netcash Pay Now), and gateways that can't pause return 400. Sends subscription.paused. No body.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The subscription after the pause.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "paused",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": "2026-11-02T09:00:00.000Z",
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}400Not allowed from the current status, or the gateway refused. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Only active subscriptions can be paused (this one is trialing)"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/pause" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Resume a customer subscription#
/api/v1/customer-subscriptions/{id}/resumeResumes a paused subscription (resuming an active one returns it unchanged). Billing restarts at the end of the already-paid period, or now if it has passed; the status returns to active (or past_due / incomplete if it was). Sends subscription.resumed. No body.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The subscription after the resume.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "active",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": "2026-11-10T09:00:00.000Z",
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}400Not allowed from the current status, or the gateway refused. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Only active subscriptions can be paused (this one is trialing)"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/resume" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Cancel a customer subscription#
/api/v1/customer-subscriptions/{id}/cancelCancels now, or with atPeriodEnd: true at the end of the paid period (trial end for trials). Gateway billing is stopped at the gateway first; if the gateway refuses, nothing changes (400). Cancelling a cancelled or expired subscription returns it unchanged. Immediate cancellation sends subscription.cancelled (and cancels unpaid first invoices of incomplete/trialing subscriptions); a scheduled one sends subscription.updated with cancelAtPeriodEnd: true. sendEmail: false cancels without emailing the customer; external subscriptions are always cancelled silently.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
atPeriodEnd | boolean | Cancel when the paid period (or trial) ends instead of now. default false |
reason | string | max 1000 chars |
when | string | Alternative to One of: |
sendEmail | boolean | false: no cancellation email to the customer. External subscriptions are always cancelled silently. default true |
Responses#
200The subscription after the cancellation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "active",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": null,
"endsAt": "2026-11-12T08:10:00.000Z",
"cancelAtPeriodEnd": true,
"cancelledAt": null,
"cancelReason": "Moving to another provider",
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}400Not allowed from the current status, or the gateway refused. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "PayFast did not accept the cancellation. The subscription was not cancelled."
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"atPeriodEnd": true,
"reason": "Moving to another provider"
}'Change plan#
/api/v1/customer-subscriptions/{id}/change-planChanges plan, quantity and/or the recurring add-on items. proration: none (default, backwards compatible: new price from the next renewal), now (charge or credit the rest of the period; a frequency change starts a new period now), next_renewal (scheduled, see pendingChange). Gateways that bill the card themselves change the amount in place when they can (PayFast, Netcash Pay Now), otherwise the change is refused (use POST /api/v1/subscriptions/{id}/update to replace the card subscription). Sends subscription.plan_changed (or subscription.updated for items / scheduled changes) with invoiceId of any proration invoice. External subscriptions: the change is recorded without proration (proration is always none, nothing is charged) and may move to disabled plans.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
planId | string | ||||||||||||||||||||||
quantity | integer | ≥ 1 · ≤ 10 000 | |||||||||||||||||||||
items | SubscriptionItemInput[] | The complete list of recurring lines (addon / metered) after the change; matched by Show fields
| |||||||||||||||||||||
proration | string |
One of: default "none" | |||||||||||||||||||||
invoiceNow | boolean |
default true |
Responses#
200The subscription after the plan change.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
change | SubscriptionChangePreview | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
charge | object | null | Proration charge issued now: |
{
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0003pln0002abcd",
"name": "Team (annual)",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 4990,
"currency": "ZAR",
"frequency": "annually",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z"
}400Not allowed from the current status, or the gateway refused. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "The new plan is billed in USD, the subscription in ZAR"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No subscription with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Subscription not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/cmg4s9d8e0005csb0001abcd/change-plan" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"planId": "cmg4p1a2b0003pln0001abcd",
"items": [
{
"code": "website_alias",
"description": "Website alias",
"unitAmount": 250,
"quantity": 3
}
],
"proration": "now"
}'List products#
/api/v1/productsYour product catalogue in name order.
Query parameters#
| Field | Type | Description |
|---|---|---|
enabled | string | Only enabled ( One of: |
billingType | string | Filter by billing type. One of: |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Products.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Product[] | Show fields
|
{
"data": [
{
"id": "cmg4r7q6p0004prd0001abcd",
"object": "product",
"sku": "SUP-HR",
"name": "Support hour",
"description": "One hour of remote support",
"amount": 650,
"currency": "ZAR",
"billingType": "once",
"frequency": null,
"taxable": true,
"enabled": true,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}
]
}400Invalid billingType.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "billingType must be once or recurring"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/products" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a product#
/api/v1/productsCreates a catalogue product. Recurring products need a frequency and a plan with Recurring billing.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
sku | string | null | max 50 chars |
namerequired | string | 1–100 chars |
description | string | null | max 2000 chars |
amountrequired | number | > 0 · ≤ 100 000 000 |
currency | string | ISO 4217; default ZAR. |
billingType | string |
One of: default "once" |
frequency | string | null | One of: |
taxable | boolean | default true |
enabled | boolean | default true |
Responses#
201The new product.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
skurequired | string | null | |
namerequired | string | |
descriptionrequired | string | null | |
amountrequired | number | |
currencyrequired | string | |
billingTyperequired | string | One of: |
frequencyrequired | string | null | One of: |
taxablerequired | boolean | |
enabledrequired | boolean | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4r7q6p0004prd0001abcd",
"object": "product",
"sku": "SUP-HR",
"name": "Support hour",
"description": "One hour of remote support",
"amount": 650,
"currency": "ZAR",
"billingType": "once",
"frequency": null,
"taxable": true,
"enabled": true,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed (e.g. recurring without frequency, invalid currency, unknown field).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Recurring products need a frequency"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}409Idempotency-Key reused with a different body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/products" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"sku": "SUP-HR",
"name": "Support hour",
"description": "One hour of remote support",
"amount": 650
}'Get a product#
/api/v1/products/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The product.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
skurequired | string | null | |
namerequired | string | |
descriptionrequired | string | null | |
amountrequired | number | |
currencyrequired | string | |
billingTyperequired | string | One of: |
frequencyrequired | string | null | One of: |
taxablerequired | boolean | |
enabledrequired | boolean | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4r7q6p0004prd0001abcd",
"object": "product",
"sku": "SUP-HR",
"name": "Support hour",
"description": "One hour of remote support",
"amount": 650,
"currency": "ZAR",
"billingType": "once",
"frequency": null,
"taxable": true,
"enabled": true,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No product with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Product not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/products/cmg4r7q6p0004prd0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a product#
/api/v1/products/{id}Partial update; null clears sku/description. Switching to billingType: "recurring" needs a frequency and Recurring billing; switching to once clears the frequency. Idempotency-Key is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
sku | string | null | max 50 chars |
name | string | 1–100 chars |
description | string | null | max 2000 chars |
amount | number | > 0 · ≤ 100 000 000 |
currency | string | ISO 4217; default ZAR. |
billingType | string |
One of: default "once" |
frequency | string | null | One of: |
taxable | boolean | default true |
enabled | boolean | default true |
Responses#
200The updated product.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
skurequired | string | null | |
namerequired | string | |
descriptionrequired | string | null | |
amountrequired | number | |
currencyrequired | string | |
billingTyperequired | string | One of: |
frequencyrequired | string | null | One of: |
taxablerequired | boolean | |
enabledrequired | boolean | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
{
"id": "cmg4r7q6p0004prd0001abcd",
"object": "product",
"sku": "SUP-HR",
"name": "Support hour",
"description": "One hour of remote support",
"amount": 700,
"currency": "ZAR",
"billingType": "once",
"frequency": null,
"taxable": true,
"enabled": true,
"createdAt": "2026-09-28T08:00:00.000Z",
"updatedAt": "2026-09-28T08:00:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Recurring products need a frequency"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, plan feature missing, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No product with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Product not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/products/cmg4r7q6p0004prd0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 700,
"enabled": true
}'List EFT orders#
/api/v1/eft-ordersNewest first.
Query parameters#
| Field | Type | Description |
|---|---|---|
externalReference | string | |
customerId | string | |
status | string | One of: |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200EFT orders.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | EftOrder[] | Show fields
|
{
"data": [
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_review",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [
{
"id": "cmg3p0r0f0011prf0001abcd",
"fileName": "proof.pdf",
"contentType": "application/pdf",
"size": 184213,
"source": "payer",
"createdAt": "2026-09-25T09:12:00.000Z"
}
],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}
]
}400Unknown status.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of awaiting_payment, awaiting_review, paid, rejected, expired, cancelled"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or payment links, or the account is read-only (writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/eft-orders" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create an EFT order#
/api/v1/eft-ordersIssues a unique deposit reference and returns your bank details for the payer (201). Requires an enabled Manual EFT gateway, the Payment links feature and API access. Idempotent on externalReference for open orders (200).
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
amountrequired | number | > 0 · ≤ 100 000 000 | ||||||
currency | string | One of ZAR, NAD, BWP, LSL, SZL. default "ZAR" | ||||||
customerId | string | |||||||
customer | object | object | Show fields
| ||||||
description | string | max 1000 chars | ||||||
externalReference | string | Your ID. If an open order (awaiting_payment, awaiting_review or rejected) with this reference exists, it is returned with 200 instead of creating another; a different amount or currency is a 400. 1–190 chars | ||||||
metadata | MetadataInput | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||
expiresAt | string (date-time) | At least 5 minutes and at most 90 days ahead. Default: the gateway's expiry days (7 by default). | ||||||
notifyPayer | boolean | Email the customer the bank details and default false |
Responses#
200An open order with this externalReference already existed; returned unchanged.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
referencerequired | string | Unique deposit reference, e.g. | |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
externalReferencerequired | string | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
customerrequired | null | object | Show fields
| |||||||||||||||||||||
bankDetailsrequired | object | Your bank account from the Manual EFT gateway. Show these to the payer. Show fields
| |||||||||||||||||||||
paymentReferencerequired | string | The reference the payer must use on the transfer (same as | |||||||||||||||||||||
payUrlrequired | string (uri) | Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404. | |||||||||||||||||||||
proofsrequired | object[] | Show fields
| |||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
reviewedAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidAtrequired | string (date-time) | null | ||||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_payment",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}201Order created.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
referencerequired | string | Unique deposit reference, e.g. | |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
externalReferencerequired | string | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
customerrequired | null | object | Show fields
| |||||||||||||||||||||
bankDetailsrequired | object | Your bank account from the Manual EFT gateway. Show these to the payer. Show fields
| |||||||||||||||||||||
paymentReferencerequired | string | The reference the payer must use on the transfer (same as | |||||||||||||||||||||
payUrlrequired | string (uri) | Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404. | |||||||||||||||||||||
proofsrequired | object[] | Show fields
| |||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
reviewedAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidAtrequired | string (date-time) | null | ||||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_payment",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}400Validation failed, Manual EFT not set up or not available, unsupported currency, customer not found, expiresAt out of range, or an open order for this externalReference has a different amount. `notifyPayer` without a customer email address.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Manual EFT is not set up. Add a 'Manual EFT (bank transfer)' gateway with your bank details under Settings > Payment providers."
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan lacks the API or payment links, monthly transaction limit reached (`plan_limit`), or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"amount": 1250,
"customer": {
"externalReference": "CRM-1001"
},
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"notifyPayer": true
}'Get an EFT order#
/api/v1/eft-orders/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The order.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
referencerequired | string | Unique deposit reference, e.g. | |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
externalReferencerequired | string | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
customerrequired | null | object | Show fields
| |||||||||||||||||||||
bankDetailsrequired | object | Your bank account from the Manual EFT gateway. Show these to the payer. Show fields
| |||||||||||||||||||||
paymentReferencerequired | string | The reference the payer must use on the transfer (same as | |||||||||||||||||||||
payUrlrequired | string (uri) | Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404. | |||||||||||||||||||||
proofsrequired | object[] | Show fields
| |||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
reviewedAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidAtrequired | string (date-time) | null | ||||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_review",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [
{
"id": "cmg3p0r0f0011prf0001abcd",
"fileName": "proof.pdf",
"contentType": "application/pdf",
"size": 184213,
"source": "payer",
"createdAt": "2026-09-25T09:12:00.000Z"
}
],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or payment links, or the account is read-only (writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No EFT order with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "EFT order not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Upload proof of payment#
/api/v1/eft-orders/{id}/proofmultipart/form-data with one file field. The type is detected from the file's bytes: PDF, PNG or JPEG only; at most 10 MB; at most 10 files per order. Allowed while the order is awaiting_payment, awaiting_review or rejected (and not past its expiry, unless already in review). Moves the order to awaiting_review, notifies your staff and sends eft.proof_received. Uploading an identical file again is harmless (deduplicated by content hash). The Idempotency-Key header is not used on this endpoint.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
multipart/form-data · required
| Field | Type | Description |
|---|---|---|
filerequired | string (binary) | PDF, PNG or JPEG, max 10 MB. |
Responses#
200The order after the upload.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
referencerequired | string | Unique deposit reference, e.g. | |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
externalReferencerequired | string | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
customerrequired | null | object | Show fields
| |||||||||||||||||||||
bankDetailsrequired | object | Your bank account from the Manual EFT gateway. Show these to the payer. Show fields
| |||||||||||||||||||||
paymentReferencerequired | string | The reference the payer must use on the transfer (same as | |||||||||||||||||||||
payUrlrequired | string (uri) | Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404. | |||||||||||||||||||||
proofsrequired | object[] | Show fields
| |||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
reviewedAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidAtrequired | string (date-time) | null | ||||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_review",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [
{
"id": "cmg3p0r0f0011prf0001abcd",
"fileName": "proof.pdf",
"contentType": "application/pdf",
"size": 184213,
"source": "payer",
"createdAt": "2026-09-25T09:12:00.000Z"
}
],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}400Missing file, empty or unsupported file type, order not open or expired, or too many proofs.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Proof must be a PDF, PNG or JPEG file"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or payment links, or the account is read-only (writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No EFT order with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "EFT order not found"
}413File larger than 10 MB.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "File is larger than 10 MB"
}415Body is not multipart/form-data.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Send multipart/form-data with a 'file' field"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/proof" -H "Authorization: Bearer $CENTRAPOINT_API_KEY" -F "[email protected];type=application/pdf"Download a proof of payment#
/api/v1/eft-orders/{id}/proofs/{proofId}One proof-of-payment file of an EFT order, exactly as it was uploaded (by the payer on the EFT payment page, or through Upload proof of payment). proofId is an id from the order's proofs list. The Content-Type is the type detected at upload (PDF, PNG or JPEG); the file is sent as an attachment with Cache-Control: private, no-store. Requires payment links in your plan.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | |
proofIdrequired | string |
Responses#
200The file.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Content-Disposition– `attachment; filename="…"` with the file name as uploaded.X-Proof-Sha256– SHA-256 of the file (hex).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or payment links.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No such proof on this EFT order in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Proof not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/proofs/cmg3p0r0f0011prf0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Cancel an EFT order#
/api/v1/eft-orders/{id}/cancelCancels an unpaid order (awaiting_payment, awaiting_review or rejected) and its pending transaction, and sends eft.cancelled and payment.cancelled. Cancelling a cancelled order returns it unchanged. No body is required.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json
object
Responses#
200The cancelled order.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
referencerequired | string | Unique deposit reference, e.g. | |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
externalReferencerequired | string | null | ||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
customerrequired | null | object | Show fields
| |||||||||||||||||||||
bankDetailsrequired | object | Your bank account from the Manual EFT gateway. Show these to the payer. Show fields
| |||||||||||||||||||||
paymentReferencerequired | string | The reference the payer must use on the transfer (same as | |||||||||||||||||||||
payUrlrequired | string (uri) | Signed public payer page with the bank details, the reference and a proof-of-payment upload. No login needed; share it instead of building your own upload. A tampered link returns 404. | |||||||||||||||||||||
proofsrequired | object[] | Show fields
| |||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
expiresAtrequired | string (date-time) | null | ||||||||||||||||||||||
reviewedAtrequired | string (date-time) | null | ||||||||||||||||||||||
paidAtrequired | string (date-time) | null | ||||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "cancelled",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}400The order is paid or expired.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "EFT order is paid"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or payment links, or the account is read-only (writes).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No EFT order with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "EFT order not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/eft-orders/cmg3e1f2t0009eft0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"List transactions#
/api/v1/transactionsPayments in your organisation, newest first, with keyset pagination (limit, startingAfter). Use GET /api/v1/transactions/{reference} for the full detail of one payment.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | Filter by status. One of: |
type | string | Filter by type. One of: |
customerId | string | Filter by customer. |
invoiceId | string | Filter by invoice. |
paymentLinkId | string | Filter by payment link. |
subscriptionId | string | Filter by customer subscription. |
from | string (date) | Start date (YYYY-MM-DD, SAST, inclusive) on the created date. |
to | string (date) | End date (YYYY-MM-DD, SAST, inclusive) on the created date. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of transactions.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | TransactionSummary[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"id": "cmg2t1x2y0009txn0001abcd",
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"type": "invoice",
"amount": 1150,
"fee": 40.25,
"net": 1109.75,
"taxAmount": 150,
"discountAmount": null,
"currency": "ZAR",
"gateway": "payfast",
"description": "Invoice INV-00042",
"providerRef": "1234567",
"payerName": "Thandi Nkosi",
"payerEmail": "[email protected]",
"customerId": "cmg2c0s7t0003cust0001abcd",
"invoice": {
"id": "cmg2i4n5v0004inv0001abcd",
"number": "INV-00042"
},
"paymentLinkId": null,
"subscriptionId": null,
"refundedAmount": 0,
"paidAt": "2026-09-25T08:14:03.000Z",
"createdAt": "2026-09-25T08:12:40.000Z",
"receiptUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd"
}
],
"hasMore": true,
"nextCursor": "cmg2t1x2y0009txn0001abcd"
}400Invalid status/type, bad date format, or an unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of pending, complete, failed, cancelled, refunded, partially_refunded"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/transactions?status=complete" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a transaction by reference#
/api/v1/transactions/{reference}Returns the current state of a payment in your organisation, looked up by its CentraPoint payment reference. Transactions in other organisations are reported as not found.
Path parameters#
| Field | Type | Description |
|---|---|---|
referencerequired | string | CentraPoint payment reference, e.g. |
Responses#
200The transaction.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
referencerequired | string | CentraPoint payment reference. | |||||||||||||||||||||
statusrequired | string |
One of: | |||||||||||||||||||||
amountrequired | number | Gross amount in major units. | |||||||||||||||||||||
feerequired | number | null | Gateway fee, when the gateway reports it. | |||||||||||||||||||||
netrequired | number | null | Amount after the gateway fee, when reported. | |||||||||||||||||||||
currencyrequired | string | ||||||||||||||||||||||
typerequired | string |
One of: | |||||||||||||||||||||
gatewayrequired | string | Gateway type that processed the payment, e.g. | |||||||||||||||||||||
sandboxrequired | boolean | true when the payment went through a gateway set to Sandbox (test mode) in CentraPoint. For PayFast, Ozow, Yoco, Peach Payments, Paystack, Flutterwave, Pesapal, M-Pesa and MTN MoMo that setting sends the payment to the gateway's test environment, so no real money moved: never settle a real invoice or order with it. Netcash (Pay Now and debit orders), DPO and PayGate with your own credentials take their test mode from the credentials or the gateway's own portal, which CentraPoint cannot see: there it only repeats the CentraPoint setting, so keep the two the same. Manual EFT has no test mode and is always false. It is the gateway's current setting (not stored per payment), so check it when the payment arrives. | |||||||||||||||||||||
descriptionrequired | string | null | Usually the payment link title. | |||||||||||||||||||||
providerRefrequired | string | null | The gateway's own ID for the payment (e.g. PayFast pf_payment_id). | |||||||||||||||||||||
payerEmailrequired | string | null | ||||||||||||||||||||||
paymentLinkIdrequired | string | null | ID of the payment link the payment was made through, if any. | |||||||||||||||||||||
externalReferencerequired | string | null | The payment link's externalReference, the EFT order's, or the one sent when charging a saved card (POST /api/v1/customers/{id}/cards/{cardId}/charges). | |||||||||||||||||||||
eftOrderIdrequired | string | null | EFT order the payment belongs to (Manual EFT). | |||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | |||||||||||||||||||||
renewalrequired | boolean | True for later collections of a subscription. | |||||||||||||||||||||
parentReferencerequired | string | null | For renewals: reference of the first payment. | |||||||||||||||||||||
subscriptionIdrequired | string | null | Subscription started by the payment link, if any. | |||||||||||||||||||||
refundedAmountrequired | number | Total of non-failed refunds, 0 if none. | |||||||||||||||||||||
refundsrequired | Refund[] | Refunds recorded for this payment, oldest first. Failed refunds are excluded. Show fields
| |||||||||||||||||||||
invoicerequired | null | object | Show fields
| |||||||||||||||||||||
paidAtrequired | string (date-time) | null | Set when the transaction becomes complete. | |||||||||||||||||||||
createdAtrequired | string (date-time) |
{
"reference": "CP-20260925-9F3A1C7B",
"status": "partially_refunded",
"amount": 499,
"fee": 14.47,
"net": 484.53,
"currency": "ZAR",
"type": "once",
"gateway": "payfast",
"description": "Website hosting - October",
"providerRef": "2458761",
"payerEmail": "[email protected]",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "ORDER-1001",
"eftOrderId": null,
"metadata": {
"crmId": "0061x00000AbCdE"
},
"renewal": false,
"parentReference": null,
"subscriptionId": null,
"refundedAmount": 100,
"refunds": [
{
"refundNumber": "REF-7C21A9F0",
"amount": 100,
"currency": "ZAR",
"status": "processed",
"processedAt": "2026-09-26T09:30:00.000Z",
"createdAt": "2026-09-26T09:29:41.000Z"
}
],
"invoice": null,
"paidAt": "2026-09-25T08:14:03.512Z",
"createdAt": "2026-09-25T08:12:47.020Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No transaction with this reference exists in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Transaction not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/transactions/CP-20260925-9F3A1C7B" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List receipts#
/api/v1/receiptsCompleted payments (including those later refunded) as receipts, newest payment first. Keyset pagination with limit and startingAfter.
Query parameters#
| Field | Type | Description |
|---|---|---|
customerId | string | Filter by customer. |
invoiceId | string | Filter by invoice. |
from | string (date) | Start date (YYYY-MM-DD, SAST, inclusive) on the payment date. |
to | string (date) | End date (YYYY-MM-DD, SAST, inclusive) on the payment date. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of receipts.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Receipt[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"id": "cmg2t1x2y0009txn0001abcd",
"object": "receipt",
"receiptNumber": "CP-20260925-9F3A1C7B",
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 1150,
"currency": "ZAR",
"taxAmount": 150,
"discountAmount": null,
"refundedAmount": 0,
"description": "Invoice INV-00042",
"payerName": "Thandi Nkosi",
"payerEmail": "[email protected]",
"customerId": "cmg2c0s7t0003cust0001abcd",
"paymentMethod": "PayFast",
"gateway": "payfast",
"invoice": {
"id": "cmg2i4n5v0004inv0001abcd",
"number": "INV-00042",
"externalReference": "ORD-5531"
},
"paidAt": "2026-09-25T08:14:03.000Z",
"createdAt": "2026-09-25T08:12:40.000Z",
"pdfUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd?format=pdf"
}
],
"hasMore": false,
"nextCursor": null
}400Bad date format or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "from/to must be YYYY-MM-DD"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/receipts" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a receipt#
/api/v1/receipts/{id}A receipt by transaction ID or payment reference. Add ?format=pdf to download the branded receipt PDF (application/pdf) instead of JSON. Only completed, partially refunded or refunded payments have receipts.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Transaction ID or payment reference ( |
Query parameters#
| Field | Type | Description |
|---|---|---|
format | string |
One of: |
Responses#
200The receipt (JSON), or the PDF with `?format=pdf`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Transaction ID. | ||||||||||||
objectrequired | string | One of: | ||||||||||||
receiptNumberrequired | string | The payment reference. | ||||||||||||
referencerequired | string | |||||||||||||
statusrequired | string | One of: | ||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | |||||||||||||
taxAmountrequired | number | null | Tax included in the payment, when known. | ||||||||||||
discountAmountrequired | number | null | |||||||||||||
refundedAmountrequired | number | |||||||||||||
descriptionrequired | string | null | |||||||||||||
payerNamerequired | string | null | |||||||||||||
payerEmailrequired | string | null | |||||||||||||
customerIdrequired | string | null | |||||||||||||
paymentMethodrequired | string | Display name of the payment method / gateway. | ||||||||||||
gatewayrequired | string | |||||||||||||
invoicerequired | object | null | Show fields
| ||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||
createdAtrequired | string (date-time) | |||||||||||||
pdfUrlrequired | string | Relative URL of the PDF (send your API key). |
{
"id": "cmg2t1x2y0009txn0001abcd",
"object": "receipt",
"receiptNumber": "CP-20260925-9F3A1C7B",
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 1150,
"currency": "ZAR",
"taxAmount": 150,
"discountAmount": null,
"refundedAmount": 0,
"description": "Invoice INV-00042",
"payerName": "Thandi Nkosi",
"payerEmail": "[email protected]",
"customerId": "cmg2c0s7t0003cust0001abcd",
"paymentMethod": "PayFast",
"gateway": "payfast",
"invoice": {
"id": "cmg2i4n5v0004inv0001abcd",
"number": "INV-00042",
"externalReference": "ORD-5531"
},
"paidAt": "2026-09-25T08:14:03.000Z",
"createdAt": "2026-09-25T08:12:40.000Z",
"pdfUrl": "/api/v1/receipts/cmg2t1x2y0009txn0001abcd?format=pdf"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No receipt with this ID or reference (or the payment is not complete).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Receipt not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/receipts/cmg2t1x2y0009txn0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List refunds#
/api/v1/refundsRefunds, newest first, with keyset pagination.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | Filter by status. One of: |
customerId | string | Filter by customer. |
transactionReference | string | Refunds of the payment with this reference. |
from | string (date) | Start date (YYYY-MM-DD, SAST, inclusive) on the date the refund was recorded. |
to | string (date) | End date (YYYY-MM-DD, SAST, inclusive) on the date the refund was recorded. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of refunds.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | RefundRecord[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"id": "cmg4f5e6d0008rfd0001abcd",
"object": "refund",
"refundNumber": "REF-7C21A9F0",
"amount": 200,
"currency": "ZAR",
"status": "processed",
"reason": "Duplicate charge",
"providerRef": "1234567",
"customerId": "cmg2c0s7t0003cust0001abcd",
"transaction": {
"id": "cmg2t1x2y0009txn0001abcd",
"reference": "CP-20260925-9F3A1C7B",
"invoiceId": "cmg2i4n5v0004inv0001abcd"
},
"processedAt": "2026-09-26T09:00:00.000Z",
"createdAt": "2026-09-26T08:58:00.000Z",
"pdfUrl": "/api/v1/refunds/cmg4f5e6d0008rfd0001abcd?format=pdf"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status, bad date format or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of pending, processed, failed"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/refunds" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a refund#
/api/v1/refunds/{id}A refund by ID or refund number. ?format=pdf returns the refund note PDF.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Refund ID or refund number ( |
Query parameters#
| Field | Type | Description |
|---|---|---|
format | string |
One of: |
Responses#
200The refund (JSON), or the refund note PDF with `?format=pdf`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||
objectrequired | string | One of: | ||||||||||||
refundNumberrequired | string | |||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | |||||||||||||
statusrequired | string | One of: | ||||||||||||
reasonrequired | string | null | |||||||||||||
providerRefrequired | string | null | The gateway's refund ID. | ||||||||||||
customerIdrequired | string | null | |||||||||||||
transactionrequired | object | Show fields
| ||||||||||||
processedAtrequired | string (date-time) | null | |||||||||||||
createdAtrequired | string (date-time) | |||||||||||||
pdfUrlrequired | string | Relative URL of the refund note PDF. |
{
"id": "cmg4f5e6d0008rfd0001abcd",
"object": "refund",
"refundNumber": "REF-7C21A9F0",
"amount": 200,
"currency": "ZAR",
"status": "processed",
"reason": "Duplicate charge",
"providerRef": "1234567",
"customerId": "cmg2c0s7t0003cust0001abcd",
"transaction": {
"id": "cmg2t1x2y0009txn0001abcd",
"reference": "CP-20260925-9F3A1C7B",
"invoiceId": "cmg2i4n5v0004inv0001abcd"
},
"processedAt": "2026-09-26T09:00:00.000Z",
"createdAt": "2026-09-26T08:58:00.000Z",
"pdfUrl": "/api/v1/refunds/cmg4f5e6d0008rfd0001abcd?format=pdf"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No refund with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Refund not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/refunds/cmg4f5e6d0008rfd0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List payouts#
/api/v1/payoutsNewest first, with keyset pagination.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | One of: |
kind | string | One of: |
customerId | string | |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of payouts.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Payout[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"object": "payout",
"id": "cmg3p4q5r0003pay0001abcd",
"reference": "PAY-000031",
"kind": "creditor",
"status": "scheduled",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bankName": "FNB",
"accountLast4": "4821",
"amount": 12500,
"currency": "ZAR",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291",
"actionDate": "2026-10-01T00:00:00.000Z",
"submittedAt": null,
"paidAt": null,
"failureReason": null,
"customer": null,
"creditNote": null,
"createdAt": "2026-09-27T10:00:00.000Z",
"updatedAt": "2026-09-27T10:00:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}400Invalid status or kind, or unknown `startingAfter`.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "kind must be one of refund, creditor, salary"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/payouts" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Schedule a payout#
/api/v1/payoutsSchedules a creditor, salary or refund payment out of your Netcash account (Netcash Creditor & Salary Payments gateway; ZAR). Bank details are validated, stored encrypted and never returned. Emits payout.scheduled. Always send an Idempotency-Key. No plan feature beyond API access is needed.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
kindrequired | string | One of: | ||||||||||||||||||
providerId | string | Default: first enabled Netcash Creditor & Salary Payments gateway (400 if none). | ||||||||||||||||||
beneficiaryNamerequired | string | 1–50 chars | ||||||||||||||||||
beneficiaryEmail | string (email) | |||||||||||||||||||
bankrequired | BankDetailsInput | Validated like the dashboard, stored encrypted and never returned. Show fields
| ||||||||||||||||||
amountrequired | number | > 0 · ≤ 5 000 000 | ||||||||||||||||||
actionDaterequired | string (date) | YYYY-MM-DD, today or later (SAST). | ||||||||||||||||||
description | string | max 1000 chars | ||||||||||||||||||
statementRef | string | Default the beneficiary name. max 20 chars | ||||||||||||||||||
customerId | string | |||||||||||||||||||
customerExternalReference | string | max 190 chars |
Responses#
201Payout scheduled.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Idempotent-Replayed– `true` when this response is a replay of an earlier request with the same Idempotency-Key.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | ||||||||||||
idrequired | string | |||||||||||||
referencerequired | string | Account reference in the Netcash batch, e.g. | ||||||||||||
kindrequired | string | One of: | ||||||||||||
statusrequired | string | One of: | ||||||||||||
beneficiaryNamerequired | string | |||||||||||||
beneficiaryEmailrequired | string | null | |||||||||||||
bankNamerequired | string | null | |||||||||||||
accountLast4required | string | null | |||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | One of: | ||||||||||||
descriptionrequired | string | null | |||||||||||||
statementRefrequired | string | null | What the beneficiary sees (max 20). | ||||||||||||
actionDaterequired | string (date-time) | UTC midnight of the payment date. | ||||||||||||
submittedAtrequired | string (date-time) | null | |||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||
failureReasonrequired | string | null | |||||||||||||
customerrequired | object | null | Show fields
| ||||||||||||
creditNoterequired | object | null | Show fields
| ||||||||||||
createdAtrequired | string (date-time) | |||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "payout",
"id": "cmg3p4q5r0003pay0001abcd",
"reference": "PAY-000031",
"kind": "creditor",
"status": "scheduled",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bankName": "FNB",
"accountLast4": "4821",
"amount": 12500,
"currency": "ZAR",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291",
"actionDate": "2026-10-01T00:00:00.000Z",
"submittedAt": null,
"paidAt": null,
"failureReason": null,
"customer": null,
"creditNote": null,
"createdAt": "2026-09-27T10:00:00.000Z",
"updatedAt": "2026-09-27T10:00:00.000Z"
}400Validation failed; invalid bank details; no enabled payout gateway; gateway disabled; salary without a salary service key; action date in the past; customer not found.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "No Netcash Creditor & Salary Payments gateway is enabled"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/payouts" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"kind": "creditor",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bank": {
"accountHolder": "Acme Supplies (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current",
"bankName": "FNB"
},
"amount": 12500,
"actionDate": "2026-10-01",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291"
}'Get a payout#
/api/v1/payouts/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Payout ID or reference. |
Responses#
200The payout.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | ||||||||||||
idrequired | string | |||||||||||||
referencerequired | string | Account reference in the Netcash batch, e.g. | ||||||||||||
kindrequired | string | One of: | ||||||||||||
statusrequired | string | One of: | ||||||||||||
beneficiaryNamerequired | string | |||||||||||||
beneficiaryEmailrequired | string | null | |||||||||||||
bankNamerequired | string | null | |||||||||||||
accountLast4required | string | null | |||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | One of: | ||||||||||||
descriptionrequired | string | null | |||||||||||||
statementRefrequired | string | null | What the beneficiary sees (max 20). | ||||||||||||
actionDaterequired | string (date-time) | UTC midnight of the payment date. | ||||||||||||
submittedAtrequired | string (date-time) | null | |||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||
failureReasonrequired | string | null | |||||||||||||
customerrequired | object | null | Show fields
| ||||||||||||
creditNoterequired | object | null | Show fields
| ||||||||||||
createdAtrequired | string (date-time) | |||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "payout",
"id": "cmg3p4q5r0003pay0001abcd",
"reference": "PAY-000031",
"kind": "creditor",
"status": "scheduled",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bankName": "FNB",
"accountLast4": "4821",
"amount": 12500,
"currency": "ZAR",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291",
"actionDate": "2026-10-01T00:00:00.000Z",
"submittedAt": null,
"paidAt": null,
"failureReason": null,
"customer": null,
"creditNote": null,
"createdAt": "2026-09-27T10:00:00.000Z",
"updatedAt": "2026-09-27T10:00:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No payout with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Payout not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/payouts/cmg3p4q5r0003pay0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Cancel a payout#
/api/v1/payouts/{id}/cancelCancels a scheduled payout before it is submitted to Netcash; a credit note's reserved amount is released. Emits payout.cancelled.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | Payout ID or reference. |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Responses#
200The cancelled payout.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectrequired | string | One of: | ||||||||||||
idrequired | string | |||||||||||||
referencerequired | string | Account reference in the Netcash batch, e.g. | ||||||||||||
kindrequired | string | One of: | ||||||||||||
statusrequired | string | One of: | ||||||||||||
beneficiaryNamerequired | string | |||||||||||||
beneficiaryEmailrequired | string | null | |||||||||||||
bankNamerequired | string | null | |||||||||||||
accountLast4required | string | null | |||||||||||||
amountrequired | number | |||||||||||||
currencyrequired | string | One of: | ||||||||||||
descriptionrequired | string | null | |||||||||||||
statementRefrequired | string | null | What the beneficiary sees (max 20). | ||||||||||||
actionDaterequired | string (date-time) | UTC midnight of the payment date. | ||||||||||||
submittedAtrequired | string (date-time) | null | |||||||||||||
paidAtrequired | string (date-time) | null | |||||||||||||
failureReasonrequired | string | null | |||||||||||||
customerrequired | object | null | Show fields
| ||||||||||||
creditNoterequired | object | null | Show fields
| ||||||||||||
createdAtrequired | string (date-time) | |||||||||||||
updatedAtrequired | string (date-time) |
{
"object": "payout",
"id": "cmg3p4q5r0003pay0001abcd",
"reference": "PAY-000031",
"kind": "creditor",
"status": "cancelled",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bankName": "FNB",
"accountLast4": "4821",
"amount": 12500,
"currency": "ZAR",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291",
"actionDate": "2026-10-01T00:00:00.000Z",
"submittedAt": null,
"paidAt": null,
"failureReason": null,
"customer": null,
"creditNote": null,
"createdAt": "2026-09-27T10:00:00.000Z",
"updatedAt": "2026-09-27T10:00:00.000Z"
}400The payout is no longer scheduled.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "A submitted payout cannot be cancelled"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API, or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404No payout with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Payout not found"
}409The Idempotency-Key was already used with a different request body.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/payouts/cmg3p4q5r0003pay0001abcd/cancel" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"List mandates#
/api/v1/mandatesNewest first. Requires Debit orders in your plan.
Query parameters#
| Field | Type | Description |
|---|---|---|
customerId | string | Filter by customer. |
status | string | Filter by status. One of: |
accountReference | string | Exact match (case-insensitive), e.g. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Mandates.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | Mandate[] | Show fields
|
{
"data": [
{
"id": "cmg4m3n4o0006mdt0001abcd",
"object": "mandate",
"accountReference": "DO7F3A1C9B2E",
"status": "pending",
"stage": "awaiting_signature",
"customerId": "cmg2c0s7t0003cust0001abcd",
"productId": null,
"subscriptionId": null,
"description": "Monthly service fee",
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"debitDay": 1,
"startDate": "2026-10-01",
"endDate": null,
"nextDebitDate": null,
"bank": {
"name": "FNB",
"branchCode": "250655",
"accountType": "current",
"accountHolder": "T Nkosi",
"accountNumberLast4": "6789"
},
"idNumberLast4": null,
"eMandateUrl": null,
"authorisedAt": null,
"approvedAt": null,
"rejectedAt": null,
"rejectionReason": null,
"failureCount": 0,
"lastCollectedAt": null,
"agreement": {
"signed": false,
"signedAt": null,
"latest": {
"id": "cmg4a7g8r0007agr0001abcd",
"status": "open"
}
},
"createdAt": "2026-09-28T08:20:00.000Z",
"updatedAt": "2026-09-28T08:20:00.000Z"
}
]
}400Invalid status.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of pending, active, paused, cancelled"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/mandates" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Create a mandate#
/api/v1/mandatesCreates a debit order mandate (201). Bank details are validated. The mandate stays pending until authorised (and approved, when your debit order settings require mandate approval). With authority: "agreement" (default) the customer is emailed an agreement to sign online; the signing URL is not returned here. Use POST /api/v1/mandates/{id}/agreement with {"email": false} to get one. Counts towards your plan's mandate limit. Requires Debit orders.
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customerId | string | |||||||||||||||||||
customer | object | object | Show fields
| ||||||||||||||||||
providerId | string | Netcash provider; default your first enabled Netcash provider. | ||||||||||||||||||
productId | string | |||||||||||||||||||
subscriptionId | string | Customer subscription to collect. Not one your platform bills ( | ||||||||||||||||||
description | string | max 500 chars | ||||||||||||||||||
bankrequired | object | Show fields
| ||||||||||||||||||
idNumber | string | max 20 chars | ||||||||||||||||||
amountrequired | number | > 0 · ≤ 1 000 000 | ||||||||||||||||||
frequency | string | One of: default "monthly" | ||||||||||||||||||
debitDay | integer | Default: your debit order settings' default debit day. ≥ 1 · ≤ 31 | ||||||||||||||||||
startDate | string (date) | YYYY-MM-DD, today or later (default today). | ||||||||||||||||||
endDate | string (date) | After startDate. | ||||||||||||||||||
notes | string | max 2000 chars | ||||||||||||||||||
authority | string |
One of: default "agreement" | ||||||||||||||||||
confirmOfflineMandate | boolean |
Responses#
201The new mandate.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
objectrequired | string | One of: | |||||||||||||||||||||
accountReferencerequired | string |
| |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
stagerequired | string | Human stage: pending mandates are One of: | |||||||||||||||||||||
customerIdrequired | string | ||||||||||||||||||||||
productIdrequired | string | null | ||||||||||||||||||||||
subscriptionIdrequired | string | null | Customer subscription the mandate collects. | |||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | One of: | |||||||||||||||||||||
frequencyrequired | string | One of: | |||||||||||||||||||||
debitDayrequired | integer | ||||||||||||||||||||||
startDaterequired | string (date) | ||||||||||||||||||||||
endDaterequired | string (date) | null | ||||||||||||||||||||||
nextDebitDaterequired | string (date) | null | ||||||||||||||||||||||
bankrequired | object | Show fields
| |||||||||||||||||||||
idNumberLast4required | string | null | ||||||||||||||||||||||
eMandateUrlrequired | string | null | Netcash e-mandate URL while waiting for the customer to sign it. | |||||||||||||||||||||
authorisedAtrequired | string (date-time) | null | When the customer authorised it (signed agreement, e-mandate, or created as offline). | |||||||||||||||||||||
approvedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
failureCountrequired | integer | Consecutive unpaids; 3 pauses the mandate. | |||||||||||||||||||||
lastCollectedAtrequired | string (date) | null | ||||||||||||||||||||||
agreement | object | Online agreement state (latest of the last 5 agreements). Show fields
| |||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||
updatedAtrequired | string (date-time) | ||||||||||||||||||||||
warningsrequired | string[] | Non-blocking bank account validation warnings. | |||||||||||||||||||||
agreementSent | object | With Show fields
|
{
"id": "cmg4m3n4o0006mdt0001abcd",
"object": "mandate",
"accountReference": "DO7F3A1C9B2E",
"status": "pending",
"stage": "awaiting_signature",
"customerId": "cmg2c0s7t0003cust0001abcd",
"productId": null,
"subscriptionId": null,
"description": "Monthly service fee",
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"debitDay": 1,
"startDate": "2026-10-01",
"endDate": null,
"nextDebitDate": null,
"bank": {
"name": "FNB",
"branchCode": "250655",
"accountType": "current",
"accountHolder": "T Nkosi",
"accountNumberLast4": "6789"
},
"idNumberLast4": null,
"eMandateUrl": null,
"authorisedAt": null,
"approvedAt": null,
"rejectedAt": null,
"rejectionReason": null,
"failureCount": 0,
"lastCollectedAt": null,
"agreement": {
"signed": false,
"signedAt": null,
"latest": {
"id": "cmg4a7g8r0007agr0001abcd",
"status": "open"
}
},
"createdAt": "2026-09-28T08:20:00.000Z",
"updatedAt": "2026-09-28T08:20:00.000Z",
"warnings": [],
"agreementSent": {
"id": "cmg4a7g8r0007agr0001abcd",
"emailed": true,
"expiresAt": "2026-10-12T08:20:00.000Z"
}
}400Validation failed: bank details, start date in the past, no Netcash provider, offline without confirmOfflineMandate, etc.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Branch code must be 6 digits and account number 5-20 digits"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Debit orders not in your plan, mandate limit reached (`plan_limit`), or account read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_limit",
"message": "Active debit order mandates limit reached (50/50) on the Business plan. Upgrade under Settings > Billing."
}409`idempotency_conflict`: Idempotency-Key reused with a different body. `external_subscription`: `subscriptionId` is a subscription your platform bills (`collectionMethod: external`), which CentraPoint never collects.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body"
}{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot collect it with a debit order. Create the mandate without subscriptionId."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/mandates" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"externalReference": "CRM-1001"
},
"description": "Monthly service fee",
"bank": {
"name": "FNB",
"branchCode": "250655",
"accountNumber": "62123456789",
"accountType": "current",
"accountHolder": "T Nkosi"
},
"amount": 499,
"frequency": "monthly",
"debitDay": 1,
"startDate": "2026-10-01"
}'Get a mandate#
/api/v1/mandates/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The mandate.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
objectrequired | string | One of: | |||||||||||||||||||||
accountReferencerequired | string |
| |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
stagerequired | string | Human stage: pending mandates are One of: | |||||||||||||||||||||
customerIdrequired | string | ||||||||||||||||||||||
productIdrequired | string | null | ||||||||||||||||||||||
subscriptionIdrequired | string | null | Customer subscription the mandate collects. | |||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | One of: | |||||||||||||||||||||
frequencyrequired | string | One of: | |||||||||||||||||||||
debitDayrequired | integer | ||||||||||||||||||||||
startDaterequired | string (date) | ||||||||||||||||||||||
endDaterequired | string (date) | null | ||||||||||||||||||||||
nextDebitDaterequired | string (date) | null | ||||||||||||||||||||||
bankrequired | object | Show fields
| |||||||||||||||||||||
idNumberLast4required | string | null | ||||||||||||||||||||||
eMandateUrlrequired | string | null | Netcash e-mandate URL while waiting for the customer to sign it. | |||||||||||||||||||||
authorisedAtrequired | string (date-time) | null | When the customer authorised it (signed agreement, e-mandate, or created as offline). | |||||||||||||||||||||
approvedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
failureCountrequired | integer | Consecutive unpaids; 3 pauses the mandate. | |||||||||||||||||||||
lastCollectedAtrequired | string (date) | null | ||||||||||||||||||||||
agreement | object | Online agreement state (latest of the last 5 agreements). Show fields
| |||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4m3n4o0006mdt0001abcd",
"object": "mandate",
"accountReference": "DO7F3A1C9B2E",
"status": "pending",
"stage": "awaiting_signature",
"customerId": "cmg2c0s7t0003cust0001abcd",
"productId": null,
"subscriptionId": null,
"description": "Monthly service fee",
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"debitDay": 1,
"startDate": "2026-10-01",
"endDate": null,
"nextDebitDate": null,
"bank": {
"name": "FNB",
"branchCode": "250655",
"accountType": "current",
"accountHolder": "T Nkosi",
"accountNumberLast4": "6789"
},
"idNumberLast4": null,
"eMandateUrl": null,
"authorisedAt": null,
"approvedAt": null,
"rejectedAt": null,
"rejectionReason": null,
"failureCount": 0,
"lastCollectedAt": null,
"agreement": {
"signed": false,
"signedAt": null,
"latest": {
"id": "cmg4a7g8r0007agr0001abcd",
"status": "open"
}
},
"createdAt": "2026-09-28T08:20:00.000Z",
"updatedAt": "2026-09-28T08:20:00.000Z"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403No API access, or the plan feature is missing.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No mandate with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Mandate not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/mandates/cmg4m3n4o0006mdt0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Update a mandate#
/api/v1/mandates/{id}Changes the amount and/or debit day, or pauses, resumes or cancels the mandate. Pending mandates can't be set active (they activate once authorised and approved). Idempotency-Key is not used.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
amount | number | > 0 · ≤ 1 000 000 |
debitDay | integer | ≥ 1 · ≤ 31 |
status | string |
One of: |
Responses#
200The updated mandate.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||
objectrequired | string | One of: | |||||||||||||||||||||
accountReferencerequired | string |
| |||||||||||||||||||||
statusrequired | string | One of: | |||||||||||||||||||||
stagerequired | string | Human stage: pending mandates are One of: | |||||||||||||||||||||
customerIdrequired | string | ||||||||||||||||||||||
productIdrequired | string | null | ||||||||||||||||||||||
subscriptionIdrequired | string | null | Customer subscription the mandate collects. | |||||||||||||||||||||
descriptionrequired | string | null | ||||||||||||||||||||||
amountrequired | number | ||||||||||||||||||||||
currencyrequired | string | One of: | |||||||||||||||||||||
frequencyrequired | string | One of: | |||||||||||||||||||||
debitDayrequired | integer | ||||||||||||||||||||||
startDaterequired | string (date) | ||||||||||||||||||||||
endDaterequired | string (date) | null | ||||||||||||||||||||||
nextDebitDaterequired | string (date) | null | ||||||||||||||||||||||
bankrequired | object | Show fields
| |||||||||||||||||||||
idNumberLast4required | string | null | ||||||||||||||||||||||
eMandateUrlrequired | string | null | Netcash e-mandate URL while waiting for the customer to sign it. | |||||||||||||||||||||
authorisedAtrequired | string (date-time) | null | When the customer authorised it (signed agreement, e-mandate, or created as offline). | |||||||||||||||||||||
approvedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectedAtrequired | string (date-time) | null | ||||||||||||||||||||||
rejectionReasonrequired | string | null | ||||||||||||||||||||||
failureCountrequired | integer | Consecutive unpaids; 3 pauses the mandate. | |||||||||||||||||||||
lastCollectedAtrequired | string (date) | null | ||||||||||||||||||||||
agreement | object | Online agreement state (latest of the last 5 agreements). Show fields
| |||||||||||||||||||||
createdAtrequired | string (date-time) | ||||||||||||||||||||||
updatedAtrequired | string (date-time) |
{
"id": "cmg4m3n4o0006mdt0001abcd",
"object": "mandate",
"accountReference": "DO7F3A1C9B2E",
"status": "pending",
"stage": "awaiting_signature",
"customerId": "cmg2c0s7t0003cust0001abcd",
"productId": null,
"subscriptionId": null,
"description": "Monthly service fee",
"amount": 549,
"currency": "ZAR",
"frequency": "monthly",
"debitDay": 1,
"startDate": "2026-10-01",
"endDate": null,
"nextDebitDate": null,
"bank": {
"name": "FNB",
"branchCode": "250655",
"accountType": "current",
"accountHolder": "T Nkosi",
"accountNumberLast4": "6789"
},
"idNumberLast4": null,
"eMandateUrl": null,
"authorisedAt": null,
"approvedAt": null,
"rejectedAt": null,
"rejectionReason": null,
"failureCount": 0,
"lastCollectedAt": null,
"agreement": {
"signed": false,
"signedAt": null,
"latest": {
"id": "cmg4a7g8r0007agr0001abcd",
"status": "open"
}
},
"createdAt": "2026-09-28T08:20:00.000Z",
"updatedAt": "2026-09-28T08:20:00.000Z"
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Send amount, debitDay and/or status"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Debit orders not in your plan, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No mandate with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Mandate not found"
}409`status: "active"` for a mandate that is not paused.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Only paused mandates can be resumed; pending mandates activate once authorised (and approved)"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/mandates/cmg4m3n4o0006mdt0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 549
}'Issue a mandate agreement#
/api/v1/mandates/{id}/agreementIssues a new debit order agreement for online signing (any open one is withdrawn) and returns its signing URL, valid for 14 days. Emails it to the customer unless email: false. Not idempotent: the response carries a signing token and is never stored for replay.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json
| Field | Type | Description |
|---|---|---|
email | boolean |
default true |
notes | string | max 2000 chars |
Responses#
201The agreement.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
mandateIdrequired | string | |
statusrequired | string |
|
signUrlrequired | string | Public signing page. Treat it as a secret; valid until |
expiresAtrequired | string (date-time) | |
emailedrequired | boolean |
{
"id": "cmg4a7g8r0007agr0001abcd",
"object": "mandate_agreement",
"mandateId": "cmg4m3n4o0006mdt0001abcd",
"status": "pending",
"signUrl": "https://app.centrapoint.co.za/sign-mandate/3q9…",
"expiresAt": "2026-10-12T08:20:00.000Z",
"emailed": false
}400Validation failed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "Invalid body"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Debit orders not in your plan, or the account is read-only.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "account_restricted",
"message": "Your free trial has ended. Choose a plan to continue."
}404No mandate with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Mandate not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/mandates/cmg4m3n4o0006mdt0001abcd/agreement" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": false
}'List reconciliation runs#
/api/v1/reconciliation/runsStatement imports (Netcash statements per Netcash account and CSV uploads) with their results, newest first by start time. Requires the Reconciliation feature (Business plan and above).
Query parameters#
| Field | Type | Description |
|---|---|---|
from | string (date) | YYYY-MM-DD (South African time): runs started on or after this day. |
to | string (date) | YYYY-MM-DD (South African time): runs started on or before this day. |
account | string | Only runs of this Netcash account ( |
source | string |
One of: |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
Responses#
200Runs.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | ReconciliationRun[] | Show fields
|
{
"data": [
{
"id": "cmg3r7c0n0013run0001abcd",
"source": "netcash_statement",
"account": {
"id": "acct_3f9a1c7b20d4e5f6",
"providers": [
{
"id": "cmg3prov0000paynow000001",
"name": "Card payments",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000recur0000002",
"name": "Subscriptions",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000credit000003",
"name": "Payouts",
"type": "netcash_creditor"
}
]
},
"statementDate": "2026-09-24T22:00:00.000Z",
"periodStart": "2026-09-23T22:00:00.000Z",
"periodEnd": "2026-09-24T22:00:00.000Z",
"status": "exceptions",
"lineCount": 42,
"matched": 38,
"unmatched": 1,
"notReceived": 1,
"exceptions": 2,
"totals": {
"receipts": 48250.5,
"fees": 612.4,
"refunds": 499,
"payouts": 33000,
"settlements": 33000,
"disbursements": 12000,
"unpaids": 350
},
"openingBalance": 1203.55,
"closingBalance": 2992.65,
"balance": {
"opening": 1203.55,
"collections": 48250.5,
"unpaids": -350,
"refunds": -499,
"fees": -612.4,
"disbursements": -12000,
"settlements": -33000,
"other": 0,
"closing": 2992.65,
"computedClosing": 2992.65,
"difference": 0
},
"trigger": "cron",
"error": null,
"createdAt": "2026-09-25T02:00:03.000Z",
"completedAt": "2026-09-25T02:04:11.000Z"
}
]
}400Bad date or unknown source.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "from and to must be YYYY-MM-DD"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or reconciliation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No Netcash account with this `account` id in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Account not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/runs?account=acct_3f9a1c7b20d4e5f6" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get a reconciliation run#
/api/v1/reconciliation/runs/{id}The run summary plus its items: every statement line except ignored ones (account fees, settlements and balances are only in totals and balance; fees linked to a payment are included), and for completed Netcash statement runs, not_received and not_debited items.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200The run with items.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
accountrequired | null | ReconciliationRunAccount | Netcash statement runs: the account and its gateways. Null for CSV imports. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statementDaterequired | string (date-time) | null | End of the statement period (or its start when no end is known). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
periodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
periodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
lineCountrequired | integer | Statement lines imported. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
matchedrequired | integer | Lines matched to a CentraPoint payment or payout. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
unmatchedrequired | integer | Lines no payment or payout could be found for. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
notReceivedrequired | integer | Number of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
exceptionsrequired | integer | Items needing attention (mismatches, unmatched lines and not_received / not_debited items). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
totalsrequired | ReconciliationTotals | Positive sums of the statement lines in each category. Settlements, unlinked fees and balance lines are counted here but are not items. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
openingBalancerequired | number | null | From the statement's opening balance line, if present. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
closingBalancerequired | number | null | From the statement's closing balance line, if present. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
balancerequired | ReconciliationBalance | Signed balance view: money in positive, money out negative. Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
triggerrequired | string | null |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
errorrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
completedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
itemsrequired | ReconciliationItem[] | Show fields
|
{
"id": "cmg3r7c0n0013run0001abcd",
"source": "netcash_statement",
"account": {
"id": "acct_3f9a1c7b20d4e5f6",
"providers": [
{
"id": "cmg3prov0000paynow000001",
"name": "Card payments",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000recur0000002",
"name": "Subscriptions",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000credit000003",
"name": "Payouts",
"type": "netcash_creditor"
}
]
},
"statementDate": "2026-09-24T22:00:00.000Z",
"periodStart": "2026-09-23T22:00:00.000Z",
"periodEnd": "2026-09-24T22:00:00.000Z",
"status": "exceptions",
"lineCount": 42,
"matched": 38,
"unmatched": 1,
"notReceived": 1,
"exceptions": 2,
"totals": {
"receipts": 48250.5,
"fees": 612.4,
"refunds": 499,
"payouts": 33000,
"settlements": 33000,
"disbursements": 12000,
"unpaids": 350
},
"openingBalance": 1203.55,
"closingBalance": 2992.65,
"balance": {
"opening": 1203.55,
"collections": 48250.5,
"unpaids": -350,
"refunds": -499,
"fees": -612.4,
"disbursements": -12000,
"settlements": -33000,
"other": 0,
"closing": 2992.65,
"computedClosing": 2992.65,
"difference": 0
},
"trigger": "cron",
"error": null,
"createdAt": "2026-09-25T02:00:03.000Z",
"completedAt": "2026-09-25T02:04:11.000Z",
"items": [
{
"id": "cmg3line000000000000001",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "matched",
"matchStatus": "matched",
"category": "collection",
"kind": "collection",
"code": "PNC",
"reference": "CP-20260924-9F3A1C7B",
"externalReference": "ORDER-1001",
"transactionId": "cmg3tx00000000000000001",
"payoutId": null,
"payoutReference": null,
"expectedAmount": 499,
"statementAmount": 499,
"date": "2026-09-24T00:00:00.000Z",
"description": "Pay Now card CP-20260924-9F3A1C7B",
"note": "Confirmed by statement"
},
{
"id": "cmg3line000000000000002",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "matched",
"matchStatus": "matched",
"category": "fee",
"kind": "fee",
"code": "NSF",
"reference": "CP-20260924-9F3A1C7B",
"externalReference": null,
"transactionId": "cmg3tx00000000000000001",
"payoutId": null,
"payoutReference": null,
"expectedAmount": 499,
"statementAmount": -14.97,
"date": "2026-09-24T00:00:00.000Z",
"description": "Pay Now fee CP-20260924-9F3A1C7B",
"note": "Fee 14.97 recorded on CP-20260924-9F3A1C7B"
},
{
"id": "cmg3line000000000000003",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "amount_mismatch",
"matchStatus": "exception",
"category": "collection",
"kind": "collection",
"code": "PNC",
"reference": "CP-20260924-41D07E2A",
"externalReference": "ORDER-1002",
"transactionId": "cmg3tx00000000000000002",
"payoutId": null,
"payoutReference": null,
"expectedAmount": 1200,
"statementAmount": 1100,
"date": "2026-09-24T00:00:00.000Z",
"description": "Pay Now card CP-20260924-41D07E2A",
"note": "Amount differs: statement 1100.00 vs transaction 1200.00"
},
{
"id": "cmg3line000000000000004",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "matched",
"matchStatus": "matched",
"category": "disbursement",
"kind": "payout_paid",
"code": "CRP",
"reference": "PAY-000042",
"externalReference": null,
"transactionId": null,
"payoutId": "cmg3payout0000000000042",
"payoutReference": "PAY-000042",
"expectedAmount": -1500,
"statementAmount": -1500,
"date": "2026-09-24T00:00:00.000Z",
"description": "Creditor payment | PAY-000042",
"note": "Payout PAY-000042 debited - marked paid"
},
{
"id": "cmg3line000000000000005",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "unmatched_receipt",
"matchStatus": "unmatched",
"category": "collection",
"kind": null,
"code": "PNE",
"reference": null,
"externalReference": null,
"transactionId": null,
"payoutId": null,
"payoutReference": null,
"expectedAmount": null,
"statementAmount": 75,
"date": "2026-09-24T00:00:00.000Z",
"description": "Pay Now EFT",
"note": "Money received with no CentraPoint payment"
},
{
"id": null,
"status": "not_received",
"category": "collection",
"kind": null,
"reference": "CP-20260920-7C21A9F0",
"externalReference": "ORDER-0990",
"transactionId": "cmg3tx00000000000000003",
"payoutId": null,
"payoutReference": null,
"expectedAmount": 250,
"statementAmount": null,
"date": null,
"description": "Website hosting",
"note": "Completed in CentraPoint but not on the statement after 3 days"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or reconciliation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No run with this ID in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Reconciliation run not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/runs/cmg3r7c0n0013run0001abcd" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List statement lines#
/api/v1/reconciliation/linesStatement lines across runs, newest line date first, with keyset pagination. Requires the Reconciliation feature (Business plan and above).
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string |
One of: |
category | string | Line category. One of: |
account | string | Only lines of this Netcash account ( |
runId | string | Only lines of this run. |
from | string (date) | Start date (YYYY-MM-DD, SAST, inclusive) on the statement line date. |
to | string (date) | End date (YYYY-MM-DD, SAST, inclusive) on the statement line date. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200A page of statement lines.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | ReconciliationLine[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | More items exist after this page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | Pass as |
{
"data": [
{
"id": "cmg3line000000000000005",
"runId": "cmg3r7c0n0013run0001abcd",
"status": "unmatched_receipt",
"matchStatus": "unmatched",
"category": "collection",
"kind": null,
"code": "PNE",
"reference": null,
"externalReference": null,
"transactionId": null,
"payoutId": null,
"payoutReference": null,
"expectedAmount": null,
"statementAmount": 75,
"date": "2026-09-24T00:00:00.000Z",
"description": "Pay Now EFT",
"note": "Money received with no CentraPoint payment"
}
],
"hasMore": false,
"nextCursor": null
}400Unknown status or category, bad date, or an invalid cursor.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invalid_request",
"message": "status must be one of open, matched, unmatched, exception, ignored"
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or reconciliation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}404No Netcash account with this `account` id in your organisation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Account not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/lines?account=acct_3f9a1c7b20d4e5f6" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List Netcash accounts#
/api/v1/reconciliation/accountsYour Netcash accounts (Netcash gateways grouped by Account service key) with the last run, open items and a 30-day balance view. Requires the Reconciliation feature (Business plan and above).
Responses#
200Accounts.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | ReconciliationAccount[] | Show fields
|
{
"data": [
{
"id": "acct_3f9a1c7b20d4e5f6",
"object": "reconciliation_account",
"providers": [
{
"id": "cmg3prov0000paynow000001",
"name": "Card payments",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000recur0000002",
"name": "Subscriptions",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000credit000003",
"name": "Payouts",
"type": "netcash_creditor"
}
],
"lastRun": {
"id": "cmg3r7c0n0013run0001abcd",
"status": "completed",
"startedAt": "2026-09-25T02:00:03.000Z",
"finishedAt": "2026-09-25T02:04:11.000Z",
"error": null
},
"lastStatement": {
"runId": "cmg3r7c0n0013run0001abcd",
"periodStart": "2026-09-23T22:00:00.000Z",
"periodEnd": "2026-09-24T22:00:00.000Z"
},
"unmatched": 1,
"unmatchedAmount": 75,
"exceptions": 1,
"notReceived": 1,
"balance": {
"periodDays": 30,
"opening": 1203.55,
"collections": 48250.5,
"unpaids": -350,
"refunds": -499,
"fees": -612.4,
"disbursements": -12000,
"settlements": -33000,
"other": 0,
"closing": 2992.65,
"computedClosing": 2992.65,
"difference": 0
}
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403Plan does not include the API or reconciliation.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "This feature is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/reconciliation/accounts" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List accounting referral links#
/api/v1/accounting/referral-linksReturns tracked sign-up links for the accounting systems CentraPoint partners with, so you can show a "Don't have Xero? Sign up" link in your own app. Only active partner programmes are returned; the list can be empty. Each url is specific to your organisation. Available on any plan with API access: signing up for an accounting system does not require CentraPoint's accounting sync feature.
Responses#
200Active referral links.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | ReferralLink[] | Show fields
|
{
"data": [
{
"connector": "xero",
"name": "Xero",
"program": "Xero App Partner",
"url": "https://app.centrapoint.co.za/r/accounting/xero?s=cpQ2VudHJhUG9pbnQx.bG9uZy1zaWduYXR1cmUx"
},
{
"connector": "zoho_books",
"name": "Zoho Books",
"program": "Zoho Affiliate",
"url": "https://app.centrapoint.co.za/r/accounting/zoho_books?s=cpQ2VudHJhUG9pbnQx.c2Vjb25kLXNpZ25hdHVyZQ"
}
]
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/accounting/referral-links" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Get your organisation and entitlements#
/api/v1/meThe calling API key's organisation, plan and full entitlements: built-in feature flags and limits (with per-organisation overrides applied) plus custom features. Use it in your own apps to decide what to enable.
Responses#
200Organisation, plan, entitlements and key.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersionrequired | string | Version of this API, e.g. | |||||||||||||||||||||||||||||||||
taxrequired | object | Your organisation's tax setting (Settings > Tax) as it is charged: what CentraPoint puts on subscription charges, payment links and document lines that carry no rate of their own. Since 1.17.0. Show fields
| |||||||||||||||||||||||||||||||||
capabilitiesrequired | object | Show fields
| |||||||||||||||||||||||||||||||||
tenantrequired | object | Show fields
| |||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| |||||||||||||||||||||||||||||||||
entitlementsrequired | object | Show fields
| |||||||||||||||||||||||||||||||||
compliance | object | Business verification (KYB). Until Show fields
| |||||||||||||||||||||||||||||||||
apiKeyrequired | object | null | Show fields
|
{
"tenant": {
"id": "cmg0t1n2t0001ten0001abcd",
"name": "Acme (Pty) Ltd",
"slug": "acme",
"accountNumber": "CP100042",
"status": "active",
"kind": "customer",
"billingCycle": "monthly",
"pendingBillingCycle": null,
"trialEndsAt": null,
"currentPeriodEnd": "2026-10-31T21:59:59.000Z"
},
"plan": {
"code": "business",
"name": "Business",
"currency": "ZAR",
"priceMonthly": 1999,
"priceYearly": 19990,
"yearlyDiscountPercent": 16.67
},
"compliance": {
"status": "approved",
"approved": true
},
"entitlements": {
"features": {
"featInvoicing": true,
"featPaymentLinks": true,
"featRecurring": true,
"featDebitOrders": true,
"featApi": true,
"featReports": true,
"featCustomerPortal": true,
"featCoupons": true
},
"limits": {
"maxUsers": 10,
"maxProviders": null,
"maxCustomers": null,
"maxMonthlyTransactions": null,
"maxApiKeys": 5,
"maxMandates": 500
},
"custom": {
"sms_notifications": {
"enabled": true,
"limit": 1000,
"label": "SMS notifications"
}
}
},
"apiKey": {
"name": "Production",
"prefix": "cp_1a2b3c4d",
"createdAt": "2026-09-01T10:00:00.000Z"
}
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/me" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Check one entitlement#
/api/v1/entitlements/{key}Whether your organisation has a feature. key is a built-in flag (e.g. featRecurring), a built-in limit (e.g. maxUsers) or a custom feature key (e.g. sms_notifications). Any valid API key may call this, even when the plan has no REST API.
Path parameters#
| Field | Type | Description |
|---|---|---|
keyrequired | string |
Responses#
200The entitlement.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
keyrequired | string | |
enabledrequired | boolean | For limits: false only when the limit is 0. |
limitrequired | integer | null | The limit value; null = unlimited or not a limit. |
{
"key": "featRecurring",
"enabled": true,
"limit": null
}401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}404Unknown key.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_found",
"message": "Feature not found"
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/entitlements/featRecurring" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Preview a change#
/api/v1/customer-subscriptions/{id}/preview-changeSame body as change-plan; nothing changes. Returns the current and new per-cycle amounts (subtotal, tax, total), the proration invoice (lines with billing periods, whether it is due now) and the next renewal invoice.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
planId | string | ||||||||||||||||||||||
quantity | integer | ≥ 1 · ≤ 10 000 | |||||||||||||||||||||
items | SubscriptionItemInput[] | The complete list of recurring lines (addon / metered) after the change; matched by Show fields
| |||||||||||||||||||||
proration | string |
One of: default "none" | |||||||||||||||||||||
invoiceNow | boolean |
default true |
Responses#
200Preview a change
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||
subscriptionId | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
requestedProration | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
proration | string | What will apply (e.g. | |||||||||||||||||||||||||||||||||||||||||||||||||||
note | string | null | ||||||||||||||||||||||||||||||||||||||||||||||||||||
effectiveAt | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||
currency | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
current | object | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||
next | object | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||
prorationInvoice | object | null | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||
nextInvoice | object | null | Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/preview-change" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"quantity": 5,
"proration": "now"
}'Reactivate a subscription#
/api/v1/customer-subscriptions/{id}/reactivateReactivates a cancelled or expired subscription (or undoes a scheduled cancellation). Billing resumes on nextBillingAt (default now; the next billing run issues the charge, or chargeNow: true bills immediately). A subscription that never paid starts again as incomplete with a new first charge. Sends subscription.reactivated. External subscriptions are reactivated silently (no charge, email or webhook; chargeNow is refused with 409 external_subscription); then record the period with sync-period.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
nextBillingAt | string | |
chargeNow | boolean |
Responses#
200Reactivate a subscription
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/reactivate" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Record your platform's period (external subscriptions)#
/api/v1/customer-subscriptions/{id}/sync-periodFor collectionMethod: external subscriptions only: records your platform's current period and status after its own renewal or status change. A period that starts where the recorded one ended counts as a renewal (cyclesBilled + 1); sending the recorded period and status again changes nothing. A scheduled cancellation moves to the new period end. A period that starts and ends before the recorded one with the same status is refused with 409 stale_period (an older update arriving late); keep the recorded start to correct the current period. Two identical calls at the same time record one renewal. Nothing is charged, emailed or sent as a webhook.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
currentPeriodStartrequired | string |
|
currentPeriodEndrequired | string | After |
status | string | Default: unchanged. One of: |
Responses#
200The subscription with the recorded period.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`not_external`: CentraPoint bills this subscription itself. `invalid_state`: the subscription is cancelled or expired (reactivate it first). `stale_period`: the period starts and ends before the recorded one and the status is the same (a late retry): nothing changed. `concurrent_update`: other updates of the subscription kept winning while this one was applied: nothing changed, send it again.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "not_external",
"message": "sync-period is only for subscriptions with collectionMethod external: CentraPoint bills this one itself"
}{
"error": "stale_period",
"message": "The recorded period (2026-10-31T04:00:00.000Z to 2026-11-30T04:00:00.000Z) is later than this one, so this looks like an older update that arrived late. Nothing changed."
}{
"error": "concurrent_update",
"message": "The subscription kept changing while this sync-period was applied (other updates at the same time). Nothing changed: send it again."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/sync-period" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"currentPeriodStart": "2026-10-31",
"currentPeriodEnd": "2026-11-30",
"status": "active"
}'Add credit#
/api/v1/customer-subscriptions/{id}/creditCredit (price-list amount) taken off the next charge(s); credit left over carries to later charges. Sends subscription.updated.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
amountrequired | number | > 0 |
description | string | max 500 chars |
Responses#
200Add credit
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/credit" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"amount": 150,
"description": "Downtime credit"
}'Discount the next renewal#
/api/v1/customer-subscriptions/{id}/discountOne-off discount on the next renewal: percent of the recurring amount, or a fixed amount.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
percent | number | > 0 · ≤ 100 |
amount | number | > 0 |
description | string |
Responses#
200Discount the next renewal
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/discount" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"percent": 20
}'Cancel a scheduled change#
/api/v1/customer-subscriptions/{id}/pending-changeDrops the change scheduled for the next renewal.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200Cancel a scheduled change
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X DELETE "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/pending-change" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List items#
/api/v1/customer-subscriptions/{id}/itemsLive lines: add-ons, metered lines and one-time lines not billed yet.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200List items
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | SubscriptionItem[] | Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Add an item#
/api/v1/customer-subscriptions/{id}/itemsone_time lines go on the next charge. Recurring lines change the per-cycle amount; proration as for change-plan.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
code | string | max 100 chars |
descriptionrequired | string | max 500 chars |
unitAmountrequired | number | Negative only for |
quantity | integer | ≥ 1 · ≤ 100 000 · default 1 |
kind | string | One of: default "addon" |
metadata | object | |
proration | string | One of: |
invoiceNow | boolean |
Responses#
201Add an item
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
change | SubscriptionChangePreview | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
charge | object | null | Proration charge issued now: |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`external_subscription`: the subscription is billed by your platform (`collectionMethod: external`); CentraPoint only records it. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "external_subscription",
"message": "Billed by Acme Hosting: CentraPoint only records this subscription and cannot pause it. Pause it on the platform and sync its status."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"code": "website_alias",
"description": "Website alias",
"unitAmount": 250,
"quantity": 3,
"proration": "now"
}'Replace the recurring items#
/api/v1/customer-subscriptions/{id}/itemsSets the complete list of recurring (addon / metered) lines; matched by code (metered usage kept).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
itemsrequired | SubscriptionItemInput[] | Show fields
| |||||||||||||||||||||
proration | string | One of: | |||||||||||||||||||||
invoiceNow | boolean |
Responses#
200Replace the recurring items
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
change | SubscriptionChangePreview | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
charge | object | null | Proration charge issued now: |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PUT "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Update an item#
/api/v1/customer-subscriptions/{id}/items/{itemId}Change description, unitAmount or quantity (with proration).
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | |
itemIdrequired | string | Item id or its |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
description | string | |
unitAmount | number | |
quantity | integer | |
metadata | object | |
proration | string | One of: |
invoiceNow | boolean |
Responses#
200Update an item
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
change | SubscriptionChangePreview | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
charge | object | null | Proration charge issued now: |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X PATCH "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Remove an item#
/api/v1/customer-subscriptions/{id}/items/{itemId}Query proration = none (default) | now | next_renewal.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | |
itemIdrequired | string | Item id or its |
Query parameters#
| Field | Type | Description |
|---|---|---|
proration | string | One of: |
Responses#
200Remove an item
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
objectrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planrequired | object | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionMethodrequired | string |
One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectedByCentraPointrequired | boolean | false for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billedByrequired | string | null | External subscriptions: the platform that bills it ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quantityrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountrequired | number | Amount per billing period: plan price × quantity, less a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
frequencyrequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingCyclesrequired | integer | null | From the plan; null = until cancelled. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cyclesBilledrequired | integer | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
startedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trialEndsAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodStartrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currentPeriodEndrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextBillingAtrequired | string (date-time) | null | Next charge (trial end for trials); null when nothing more will be billed. External subscriptions: your platform's next renewal, for information. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
endsAtrequired | string (date-time) | null | When the subscription ends (scheduled cancellation or fixed term). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelAtPeriodEndrequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelledAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancelReasonrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pausedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resumedAtrequired | string (date-time) | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dunningAttemptsrequired | integer | Failed-payment retries so far (0 when paid up). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gatewayrequired | string | null | Gateway type of the provider, e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentTokenIdrequired | string | null | Gateway subscription/token collecting it (the same ID as the gateway subscription in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
couponIdrequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
externalReferencerequired | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourcerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
events | object[] | Only with Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planAmount | number | Plan part of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
billingAnchorDay | integer | null | Day of month renewals fall on (clamped to the month end). ≥ 1 · ≤ 31 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
items | SubscriptionItem[] | Live lines: recurring add-ons, metered lines and one-time lines not billed yet (credits, discounts, proration). Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pendingChange | object | null | A change scheduled for the next renewal ( Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
change | SubscriptionChangePreview | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
charge | object | null | Proration charge issued now: |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X DELETE "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Record metered usage#
/api/v1/customer-subscriptions/{id}/items/{itemId}/usageAdds (increment, default) or sets usage of a metered item for the current period. Billed at the next renewal, then reset. Send an Idempotency-Key to avoid double counting on retries.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | |
itemIdrequired | string | Item id or its |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
quantityrequired | integer | |
action | string | One of: |
Responses#
200Record metered usage
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
idrequired | string | |
objectrequired | string | One of: |
kindrequired | string |
One of: |
coderequired | string | null | Your key for the line, e.g. |
descriptionrequired | string | |
unitAmountrequired | number | Price-list amount per unit (same tax basis as plan prices). |
quantityrequired | integer | |
usageQuantity | integer |
|
discountPercent | number | null |
|
periodStart | string (date-time) | null | |
periodEnd | string (date-time) | null | |
billedAt | string (date-time) | null | |
invoiceId | string | null | |
amountrequired | number | unitAmount x quantity (metered: x usageQuantity). |
metadata | object | null | |
createdAtrequired | string (date-time) | |
updatedAtrequired | string (date-time) |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/items/itemId/usage" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"quantity": 120
}'List a subscription's invoices#
/api/v1/customer-subscriptions/{id}/invoicesNewest first. Each invoice has the fields of GET /api/v1/invoices/{id} (billing period as inclusive YYYY-MM-DD dates, lines with details and their own periods), plus charge and cycle.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Query parameters#
| Field | Type | Description |
|---|---|---|
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200List a subscription's invoices
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | SubscriptionInvoice[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/invoices" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List a subscription's payments#
/api/v1/customer-subscriptions/{id}/paymentsPayment attempts (transactions), newest first. Filter with status.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200List a subscription's payments
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | SubscriptionPayment[] | Show fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/customer-subscriptions/id/payments" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Change amount or next charge date#
/api/v1/subscriptions/{id}/updateChanges the amount (what the payer pays) and/or next charge date (YYYY-MM-DD). In place where the gateway supports it (PayFast and Netcash Pay Now: amount and date; result.mode: updated). Otherwise an amount change uses the replace flow: the payer is emailed a new recurring checkout at the new amount (result.mode: replace, result.payUrl); once it is paid the old gateway subscription is cancelled (Netcash DeleteSubscription) and subscription.cancelled is sent for the old one. While that checkout is unpaid, a replacement at the same amount emails the same link again (same paymentLinkId / payUrl) instead of a second one; a replacement at another amount deactivates it (if the payer still completes it, it replaces the subscription and the newer link is deactivated); two replacements at the same time leave one open link. If the payer completes one checkout link twice, only the first payment replaces the subscription: the card subscription the second one started is cancelled at the gateway where the gateway can (otherwise the report says so, and it keeps collecting until you cancel it on the gateway's dashboard) and that payment is reported to your staff to refund. When the subscription is replaced, its unpaid retry links are deactivated. replace: false refuses instead. A token that collects a customer subscription must be changed through the customer subscription.
Invoice-linked subscriptions (started by a recurring payment link created with invoiceId) invoice every payment with a copy of the latest invoice's lines, so their amount is those lines' total and cannot change: another amount returns 409 invoice_linked and nothing is changed (a new nextDate is still accepted). A subscription whose amount was changed before 1.14.1 and no longer matches its lines can be set back to the lines total. Only the current replacement checkout replaces an invoice-linked subscription: a payment on an earlier one leaves the subscription as it is and is reported to your staff (audit log payment.renewal_unallocated and a notification). To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
amount | number | |
nextDate | string (date) | |
replace | boolean | default true |
sendEmail | boolean | default true |
Responses#
200Change amount or next charge date
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||
statusrequired | string | One of: | ||||||||||||||||||||||||
frequencyrequired | string | null | One of: | ||||||||||||||||||||||||
amountrequired | number | null | Amount of each collection. | ||||||||||||||||||||||||
currencyrequired | string | |||||||||||||||||||||||||
gatewayrequired | string | Gateway that bills the subscription, e.g. | ||||||||||||||||||||||||
paymentLinkIdrequired | string | null | The recurring payment link that started it. | ||||||||||||||||||||||||
externalReferencerequired | string | null | That link's externalReference. | ||||||||||||||||||||||||
metadatarequired | Metadata | Your own key/value data. Flat map of strings (numbers and booleans are converted to strings; null values are dropped). Up to 50 keys; keys 1–40 characters of letters, digits, | ||||||||||||||||||||||||
createdAtrequired | string (date-time) | |||||||||||||||||||||||||
updatedAtrequired | string (date-time) | |||||||||||||||||||||||||
capabilities | GatewaySubscriptionCapabilities | What the gateway supports for this subscription (GET /subscriptions/{id} and update responses). Show fields
| ||||||||||||||||||||||||
replacementLinkId | string | null | Checkout link emailed to replace this subscription (new amount / re-authorised card). | ||||||||||||||||||||||||
result | object | Show fields
|
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`invoice_linked`: the subscription is invoice-linked and the amount would change. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "invoice_linked",
"message": "This subscription is billed with invoice INV-000042: every payment is invoiced with a copy of its lines (R 299,00), so an amount change cannot use another amount. To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/id/update" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"amount": 599
}'Retry a failed charge#
/api/v1/subscriptions/{id}/retryRe-collects the latest missed charge that has not been re-collected yet: a failed gateway renewal or charged retry of this subscription (a failed retry stands for the charge it retried). A payer's declined attempt on a retry link or replacement checkout is not a missed charge, and neither is a failed renewal of the card subscription a replacement checkout started (retry that subscription instead). Tokens CentraPoint can charge itself are charged now (mode: charged); otherwise the payer is emailed a once-off payment link for the amount (mode: payment_link; an earlier unpaid retry link for the same charge is deactivated). A charge is re-collected once: by a completed charged retry, a paid retry link, or a charged retry that is still pending (until the gateway reports its result). When no missed charge is left to re-collect, a subscription that never missed a charge is collected now (amount, or the subscription amount); one whose missed charges were all re-collected returns 409 nothing_to_retry unless you send amount, which is then collected now. Retries of one subscription are handled one at a time, so two calls at once cannot re-collect a charge twice.
For a subscription started by a payment link, a charged retry is recorded as a collection of that link, like a gateway renewal: the transaction has renewal: true (and retry: true in the charges list) and sends subscription.charged / subscription.payment_failed. Charged retries of other subscriptions have renewal: false.
Invoice-linked subscriptions (recurring payment link with invoiceId): a retry needs a missed charge that was not re-collected yet (else 409 nothing_to_retry, also with amount) and the invoice lines' total, which is the default (another amount returns 409 invoice_linked). The retry payment (charged, or the retry link once paid) is invoiced exactly once, like a renewal, for the period after the latest invoice. A second payment for a charge that was already re-collected (e.g. an earlier retry link the payer was still paying) is not invoiced: it is reported to your staff (audit log payment.renewal_unallocated and a notification) to refund or allocate.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
amount | number | |
sendEmail | boolean |
Responses#
200Retry a failed charge
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
object | string | |
subscriptionId | string | |
mode | string | One of: |
transactionId | string | |
status | string | |
payUrl | string | |
paymentLinkId | string |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
409`nothing_to_retry`: no missed charge is left to re-collect (none, or each was re-collected or its charged retry is still pending) and either no `amount` was sent to a subscription that missed a charge before, or the subscription is invoice-linked (with or without `amount`). `invoice_linked`: `amount` differs from the invoice lines' total of an invoice-linked subscription. Nothing changed.
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
{
"error": "nothing_to_retry",
"message": "Every failed charge of this subscription was already re-collected (or a retry is still pending)"
}{
"error": "invoice_linked",
"message": "This subscription is billed with invoice INV-000042: every payment is invoiced with a copy of its lines (R 299,00), so a retry cannot use another amount. To bill a different amount, cancel the subscription and create a recurring payment link for a new invoice with the new lines."
}429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/id/retry" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"List charges#
/api/v1/subscriptions/{id}/chargesEvery charge of the subscription, newest first: first payment, gateway renewals, retries (charged, and payments or declined attempts on retry links) and payments or declined attempts on its replacement checkouts. The renewals of the card subscription a replacement checkout started are that subscription's charges.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Query parameters#
| Field | Type | Description |
|---|---|---|
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200List charges
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | SubscriptionCharge[] | Show fields
| ||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | |||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions/id/charges" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"List migrations#
/api/v1/subscriptions/migrationsNewest first; summary counts migrations per status.
Query parameters#
| Field | Type | Description |
|---|---|---|
status | string | |
q | string | Email, name or legacy reference contains. |
limit | integer | 1–100, default 20. Out-of-range values are clamped; invalid values fall back to 20. ≥ 1 · ≤ 100 · default 20 |
startingAfter | string | Cursor: the |
Responses#
200List migrations
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
datarequired | SubscriptionMigration[] | Show fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasMorerequired | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nextCursorrequired | string | null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
summary | object |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions/migrations" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Migrate legacy subscriptions#
/api/v1/subscriptions/migrationsOne legacy subscription (201; 200 when the legacyReference exists) or {subscriptions: [...]} (up to 500; a result per row). CentraPoint creates the customer (by email) and an incomplete gateway customer subscription, and emails the payer a recurring checkout link to re-authorise their card. When paid the subscription activates and, with cancelLegacy: on_authorised, the legacy instruction is cancelled (Netcash DeleteSubscription with the legacy reference).
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
SubscriptionMigrationInput | object
Responses#
200Bulk import result, or an existing migration.
SubscriptionMigration | object
201Migrate legacy subscriptions
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
id | string | |
object | string | One of: |
status | string | One of: |
payerName | string | |
email | string | |
phone | string | null | |
amount | number | |
currency | string | |
frequency | string | |
nextDate | string (date-time) | null | |
legacyReference | string | |
legacyGateway | string | |
externalReference | string | null | |
cancelLegacy | string | One of: |
providerId | string | null | |
customerId | string | null | |
subscriptionId | string | null | The CentraPoint customer subscription. |
paymentLinkId | string | null | |
lastError | string | null | |
notes | string | null | |
linkSentAt | string | null | |
authorisedAt | string | null | |
legacyCancelledAt | string | null | |
source | string | |
createdAt | string | |
updatedAt | string |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/migrations" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
-H "Content-Type: application/json" \
-d '{
"payerName": "Jane Smith",
"email": "[email protected]",
"amount": 115,
"frequency": "monthly",
"nextDate": "2026-11-01",
"legacyReference": "INV-2019-0042"
}'Get a migration#
/api/v1/subscriptions/migrations/{id}Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string |
Responses#
200Get a migration
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
id | string | |
object | string | One of: |
status | string | One of: |
payerName | string | |
email | string | |
phone | string | null | |
amount | number | |
currency | string | |
frequency | string | |
nextDate | string (date-time) | null | |
legacyReference | string | |
legacyGateway | string | |
externalReference | string | null | |
cancelLegacy | string | One of: |
providerId | string | null | |
customerId | string | null | |
subscriptionId | string | null | The CentraPoint customer subscription. |
paymentLinkId | string | null | |
lastError | string | null | |
notes | string | null | |
linkSentAt | string | null | |
authorisedAt | string | null | |
legacyCancelledAt | string | null | |
source | string | |
createdAt | string | |
updatedAt | string |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X GET "https://app.centrapoint.co.za/api/v1/subscriptions/migrations/id" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY"Migration actions#
/api/v1/subscriptions/migrations/{id}/{action}send-link: (re)email the checkout link. cancel-legacy: DeleteSubscription at Netcash now. mark-legacy-cancelled {note?}: it was cancelled in the Netcash portal. cancel: abandon a migration the payer has not authorised.
Path parameters#
| Field | Type | Description |
|---|---|---|
idrequired | string | |
actionrequired | string | One of: |
Request headers#
| Field | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional, up to 200 characters. Keys are scoped to your organisation, the HTTP method and the exact request path (e.g. max 200 chars |
Request body#
application/json · required
| Field | Type | Description |
|---|---|---|
note | string |
Responses#
200Migration actions
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.
| Field | Type | Description |
|---|---|---|
id | string | |
object | string | One of: |
status | string | One of: |
payerName | string | |
email | string | |
phone | string | null | |
amount | number | |
currency | string | |
frequency | string | |
nextDate | string (date-time) | null | |
legacyReference | string | |
legacyGateway | string | |
externalReference | string | null | |
cancelLegacy | string | One of: |
providerId | string | null | |
customerId | string | null | |
subscriptionId | string | null | The CentraPoint customer subscription. |
paymentLinkId | string | null | |
lastError | string | null | |
notes | string | null | |
linkSentAt | string | null | |
authorisedAt | string | null | |
legacyCancelledAt | string | null | |
source | string | |
createdAt | string | |
updatedAt | string |
400Invalid request or a business rule (`invalid_request` / `validation_error` with a message).
401The API key is missing, malformed, unknown or revoked. No rate-limit headers are sent, because the key is not known.
{
"error": "unauthorized",
"message": "Missing or malformed API key"
}{
"error": "unauthorized",
"message": "Invalid API key"
}403API access is not included in your plan.
{
"error": "plan_restricted",
"message": "API access is not included in your plan"
}404Not found (`not_found`).
429More than 120 requests in the current 60-second window for this API key, or more than 600 from one client IP before authentication (message `Too many requests from this network`; headers then describe the IP window).
Headers
X-RateLimit-Limit– Requests allowed per 60-second window for this API key.X-RateLimit-Remaining– Requests left in the current window.X-RateLimit-Reset– Unix time (seconds) when the current window ends.Retry-After– Seconds to wait before retrying.
{
"error": "rate_limited",
"message": "Rate limit of 120 requests per minute exceeded for this API key"
}500Unexpected server error. The details are logged by CentraPoint; the message is generic.
{
"error": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support."
}Code samples#
curl -X POST "https://app.centrapoint.co.za/api/v1/subscriptions/migrations/id/action" \
-H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
-H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31"Webhook events#
Sent by CentraPoint to each HTTPS endpoint configured under Settings → Webhooks and subscribed to this event. Respond 2xx within 10 seconds. Failed deliveries are retried after 1m, 5m, 30m, 2h, 6h, 12h and 24h (8 attempts). Redirects are not followed. Deliveries may repeat and may arrive out of order.
payment.complete: Payment completedpayment.failed: Payment failedpayment.cancelled: Payment cancelledpayment.refunded: Payment fully refundedpayment.partially_refunded: Payment partially refundedinvoice.created: Invoice createdinvoice.sent: Invoice sentinvoice.paid: Invoice fully paidinvoice.partially_paid: Invoice partially paidinvoice.cancelled: Invoice cancelledeft.proof_received: EFT proof of payment receivedeft.rejected: EFT proof rejectedeft.expired: EFT order expiredeft.cancelled: EFT order cancelledreconciliation.completed: Reconciliation run completedsubscription.created: Customer subscription createdsubscription.activated: Subscription activated (first payment completed)subscription.charged: Subscription renewal chargedsubscription.renewed: Customer subscription renewedsubscription.trial_ended: Customer subscription trial endedsubscription.payment_failed: Subscription renewal failedsubscription.past_due: Customer subscription past duesubscription.paused: Subscription pausedsubscription.resumed: Subscription resumedsubscription.plan_changed: Customer subscription plan changedsubscription.updated: Customer subscription updatedsubscription.cancelled: Subscription cancelledsubscription.expired: Customer subscription expiredcheckout.completed: Checkout session completedcheckout.failed: Checkout session failedquote.created: Quote createdquote.updated: Quote edited or moved back to draftquote.sent: Quote marked sentquote.accepted: Quote acceptedquote.declined: Quote declinedquote.expired: Quote expiredquote.invoiced: Quote converted to an invoicecredit_note.created: Credit note createdcredit_note.issued: Credit note issuedcredit_note.applied: Credit applied to an invoicecredit_note.refunded: Credit paid backcredit_note.voided: Credit note voidedpayout.scheduled: Payout scheduledpayout.submitted: Payout submitted to Netcashpayout.paid: Payout paidpayout.failed: Payout failedpayout.cancelled: Payout cancelledsubscription.trial_ending: Customer subscription trial endingsubscription.reactivated: Customer subscription reactivatedcustomer.payment_method.added: Saved card addedcustomer.payment_method.removed: Saved card removedcustomer.payment_method.expiring: Saved card expiringcustomer.standing.changed: Account standing changed
Headers#
| Field | Type | Description |
|---|---|---|
CentraPoint-Eventrequired | string | Event type. |
CentraPoint-Deliveryrequired | string | Delivery ID (constant across retries of this delivery). |
CentraPoint-Signaturerequired | string |
|
Payload: payment.complete, payment.failed, payment.cancelled, payment.refunded, payment.partially_refunded#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | WebhookPaymentData | Show fields
|
{
"id": "evt_3f9a1c7b2e4d6f8091a2b3c4",
"type": "payment.complete",
"created": "2026-09-25T08:14:04.201Z",
"data": {
"reference": "CP-20260925-9F3A1C7B",
"status": "complete",
"amount": 499,
"currency": "ZAR",
"type": "once",
"gateway": "payfast",
"providerRef": "2458761",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "ORDER-1001",
"eftOrderId": null,
"invoice": null,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"metadata": {
"crmId": "0061x00000AbCdE"
},
"renewal": false,
"parentReference": null,
"subscriptionId": null,
"refundedAmount": 0,
"paidAt": "2026-09-25T08:14:03.512Z"
}
}Payload: invoice.created, invoice.sent, invoice.paid, invoice.partially_paid, invoice.cancelled#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | Invoice | Show fields
|
{
"id": "evt_7f3b01c9e1a5d2b8f4c6e0a3",
"type": "invoice.created",
"created": "2026-09-25T08:05:00.000Z",
"data": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"status": "draft",
"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"
}
}Payload: eft.proof_received, eft.rejected, eft.expired, eft.cancelled#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | EftOrder | Show fields
|
{
"id": "evt_5c7e9a1b3d5f7a9c1e3b5d7f",
"type": "eft.proof_received",
"created": "2026-09-25T09:12:01.000Z",
"data": {
"id": "cmg3e1f2t0009eft0001abcd",
"reference": "EFT-7K3Q9P2M",
"status": "awaiting_review",
"amount": 1250,
"currency": "ZAR",
"description": "Order #1001",
"externalReference": "ORDER-1001",
"metadata": {
"cartId": "c_8841"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001"
},
"bankDetails": {
"bankName": "FNB",
"accountName": "Example Traders (Pty) Ltd",
"accountNumber": "62000000000",
"branchCode": "250655",
"accountType": "current"
},
"paymentReference": "EFT-7K3Q9P2M",
"payUrl": "https://app.centrapoint.co.za/eft/cmg3e1f2t0009eft0001abcd.Qm9ndXMtc2lnbmF0dXJlLWV4YW1wbGU",
"proofs": [
{
"id": "cmg3p0r0f0011prf0001abcd",
"fileName": "proof.pdf",
"contentType": "application/pdf",
"size": 184213,
"source": "payer",
"createdAt": "2026-09-25T09:12:00.000Z"
}
],
"rejectionReason": null,
"expiresAt": "2026-10-02T08:00:00.000Z",
"reviewedAt": null,
"paidAt": null,
"createdAt": "2026-09-25T08:00:00.000Z"
}
}Payload: reconciliation.completed#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | object | Show fields
|
{
"id": "evt_5c7e9a1b3d5f7a9c1e3b5d7f",
"type": "reconciliation.completed",
"created": "2026-09-25T09:12:01.000Z",
"data": {
"runId": "cmg3r7c0n0013run0001abcd",
"status": "exceptions",
"exceptions": 2,
"lineCount": 42,
"statementDate": "2026-09-24T22:00:00.000Z",
"totals": {
"receipts": 48250.5,
"fees": 612.4,
"refunds": 499,
"payouts": 33000,
"settlements": 33000,
"disbursements": 12000,
"unpaids": 350
},
"account": {
"id": "acct_3f9a1c7b20d4e5f6",
"providers": [
{
"id": "cmg3prov0000paynow000001",
"name": "Card payments",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000recur0000002",
"name": "Subscriptions",
"type": "netcash_paynow"
},
{
"id": "cmg3prov0000credit000003",
"name": "Payouts",
"type": "netcash_creditor"
}
]
},
"summary": {
"matched": 38,
"unmatched": 1,
"notReceived": 1,
"balance": {
"opening": 1203.55,
"collections": 48250.5,
"unpaids": -350,
"refunds": -499,
"fees": -612.4,
"disbursements": -12000,
"settlements": -33000,
"other": 0,
"closing": 2992.65,
"computedClosing": 2992.65,
"difference": 0
}
}
}
}Payload: subscription.created, subscription.renewed, subscription.trial_ended, subscription.past_due, subscription.plan_changed, subscription.updated, subscription.expired, subscription.trial_ending, subscription.reactivated#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | object | Show fields
|
{
"id": "evt_7b1d3f5a9c2e4a6c8e0b2d4f",
"type": "subscription.created",
"created": "2026-10-12T08:10:05.000Z",
"data": {
"id": "cmg4s9d8e0005csb0001abcd",
"object": "customer_subscription",
"status": "trialing",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"plan": {
"id": "cmg4p1a2b0002pln0001abcd",
"name": "Pro",
"packageId": "cmg4p1a2b0001pkg0001abcd",
"packageName": "Acme Cloud"
},
"collectionMethod": "invoice",
"quantity": 1,
"amount": 499,
"currency": "ZAR",
"frequency": "monthly",
"billingCycles": null,
"cyclesBilled": 0,
"startedAt": "2026-09-28T08:10:00.000Z",
"trialEndsAt": "2026-10-12T08:10:00.000Z",
"currentPeriodStart": null,
"currentPeriodEnd": null,
"nextBillingAt": "2026-10-12T08:10:00.000Z",
"endsAt": null,
"cancelAtPeriodEnd": false,
"cancelledAt": null,
"cancelReason": null,
"pausedAt": null,
"resumedAt": null,
"dunningAttempts": 0,
"gateway": null,
"providerId": null,
"paymentTokenId": null,
"couponId": null,
"externalReference": "SUB-CRM-1001-PRO",
"metadata": {
"crmDealId": "D-778"
},
"source": "api",
"createdAt": "2026-09-28T08:10:00.000Z",
"updatedAt": "2026-09-28T08:10:00.000Z",
"subscriptionId": "cmg4s9d8e0005csb0001abcd"
}
}Payload: subscription.activated, subscription.charged, subscription.payment_failed, subscription.paused, subscription.resumed, subscription.cancelled#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | SubscriptionWebhookData | Show fields
|
{
"id": "evt_2a4c6e8f0b1d3f5a7c9e1b3d",
"type": "subscription.activated",
"created": "2026-10-25T08:14:05.000Z",
"data": {
"id": "cmg2s5b8k0007sub0001abcd",
"status": "active",
"frequency": "monthly",
"amount": 499,
"currency": "ZAR",
"gateway": "payfast",
"paymentLinkId": "cmg1k2x3y0001abcd1234efgh",
"externalReference": "SUB-ACME-PRO",
"metadata": {
"plan": "pro"
},
"createdAt": "2026-09-25T08:14:04.000Z",
"updatedAt": "2026-09-25T08:14:04.000Z",
"subscriptionId": "cmg2s5b8k0007sub0001abcd",
"payment": {
"reference": "CP-20260925-9F3A1C7B",
"amount": 499,
"currency": "ZAR",
"status": "complete",
"paidAt": "2026-09-25T08:14:03.512Z"
},
"periodStart": "2026-09-25T08:14:03.512Z",
"periodEnd": "2026-10-25T08:14:03.512Z"
}
}Payload: checkout.completed, checkout.failed#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | CheckoutSession | Show fields
|
{
"id": "evt_9c1e3a5b7d9f1b3d5f7a9c1e",
"type": "checkout.completed",
"created": "2026-09-28T08:41:10.000Z",
"data": {
"id": "cmg5k1s2e0010cks0001abcd",
"object": "checkout_session",
"status": "completed",
"source": "api",
"checkoutUrl": null,
"packageId": "cmg4p1a2b0001pkg0001abcd",
"planId": "cmg4p1a2b0002pln0001abcd",
"productId": null,
"customerId": "cmg2c0s7t0003cust0001abcd",
"subscriptionId": "cmg4s9d8e0005csb0001abcd",
"couponCode": "WELCOME10",
"returnUrl": "https://www.example.co.za/thanks",
"prefill": {
"email": "[email protected]",
"firstName": "Thandi",
"lastName": "Nkosi"
},
"metadata": {
"signupId": "SU-9921"
},
"transaction": {
"id": "cmg2t1x2y0009txn0001abcd",
"reference": "CP-20260928-4B2D9E1A",
"status": "complete",
"amount": 449.1,
"currency": "ZAR",
"discountAmount": 49.9,
"taxAmount": 58.58,
"paidAt": "2026-09-28T08:41:00.000Z"
},
"expiresAt": "2026-09-29T08:30:00.000Z",
"usedAt": "2026-09-28T08:41:00.000Z",
"createdAt": "2026-09-28T08:30:00.000Z",
"updatedAt": "2026-09-28T08:30:00.000Z"
}
}Payload: quote.created, quote.updated, quote.sent, quote.accepted, quote.declined, quote.expired, quote.invoiced#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | Quote | Returned by every quote endpoint and sent as Show fields
|
{
"id": "evt_7f3b03c9e1a5d2b8f4c6e0a3",
"type": "quote.created",
"created": "2026-09-27T07:55:00.000Z",
"data": {
"object": "quote",
"id": "cmg3q1a2b0001quo0001abcd",
"number": "QUO-000017",
"status": "draft",
"issueDate": "2026-09-26T22:00:00.000Z",
"expiryDate": "2026-10-26T21:59:59.000Z",
"periodStart": null,
"periodEnd": null,
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 5000,
"taxAmount": 750,
"total": 5750,
"notes": "Valid for 30 days.",
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": null,
"lineItems": [
{
"description": "Website redesign",
"details": "5 pages, mobile layout\nTwo rounds of changes",
"quantity": 1,
"unitPrice": 4500,
"amount": 4500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
},
{
"description": "Hosting setup",
"details": null,
"quantity": 1,
"unitPrice": 500,
"amount": 500,
"taxRate": 15,
"periodStart": null,
"periodEnd": null
}
],
"sentAt": null,
"acceptedAt": null,
"declinedAt": null,
"createdAt": "2026-09-27T07:55:00.000Z",
"updatedAt": "2026-09-27T07:55:00.000Z"
}
}Payload: credit_note.created, credit_note.issued, credit_note.applied, credit_note.refunded, credit_note.voided#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | CreditNote | Returned by every credit note endpoint and sent as Show fields
|
{
"id": "evt_7f3b10c9e1a5d2b8f4c6e0a3",
"type": "credit_note.created",
"created": "2026-09-27T09:10:00.000Z",
"data": {
"object": "credit_note",
"id": "cmg3c7d8e0002crn0001abcd",
"number": "CN-000008",
"status": "draft",
"issueDate": "2026-09-27T09:10:00.000Z",
"periodStart": "2026-09-01",
"periodEnd": "2026-09-30",
"reason": "Hosting downtime 12-14 September",
"currency": "ZAR",
"taxInclusive": false,
"subtotal": 200,
"taxAmount": 30,
"total": 230,
"amountApplied": 0,
"amountRefunded": 0,
"balance": 230,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "CRM-1001",
"email": "[email protected]"
},
"invoice": {
"id": "cmg2i9n0v0005inv0001abcd",
"number": "INV-000042",
"externalReference": "ORDER-1001"
},
"lineItems": [
{
"description": "Service credit - downtime",
"details": "Outage 12-14 September (3 days)",
"quantity": 1,
"unitPrice": 200,
"amount": 200,
"taxRate": 15,
"periodStart": "2026-09-12",
"periodEnd": "2026-09-14"
}
],
"history": [],
"refunds": [],
"payouts": [],
"issuedAt": null,
"voidedAt": null,
"createdAt": "2026-09-27T09:10:00.000Z",
"updatedAt": "2026-09-27T09:10:00.000Z"
}
}Payload: payout.scheduled, payout.submitted, payout.paid, payout.failed, payout.cancelled#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | Payout | Returned by every payout endpoint and sent as Show fields
|
{
"id": "evt_7f3b15c9e1a5d2b8f4c6e0a3",
"type": "payout.scheduled",
"created": "2026-09-27T10:00:00.000Z",
"data": {
"object": "payout",
"id": "cmg3p4q5r0003pay0001abcd",
"reference": "PAY-000031",
"kind": "creditor",
"status": "scheduled",
"beneficiaryName": "Acme Supplies",
"beneficiaryEmail": "[email protected]",
"bankName": "FNB",
"accountLast4": "4821",
"amount": 12500,
"currency": "ZAR",
"description": "Invoice AS-2291",
"statementRef": "CentraPoint AS-2291",
"actionDate": "2026-10-01T00:00:00.000Z",
"submittedAt": null,
"paidAt": null,
"failureReason": null,
"customer": null,
"creditNote": null,
"createdAt": "2026-09-27T10:00:00.000Z",
"updatedAt": "2026-09-27T10:00:00.000Z"
}
}Payload: customer.payment_method.added, customer.payment_method.removed, customer.payment_method.expiring#
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | object | Show fields
|
{
"id": "evt_7f3b19c9e1a5d2b8f4c6e0a3",
"type": "customer.payment_method.added",
"created": "2026-10-05T08:03:00.000Z",
"data": {
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null,
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "platform-org:42"
}
}
}Payload: customer.standing.changed#
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idrequired | string | Unique event ID ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | One of: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createdrequired | string (date-time) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
datarequired | object | Show fields
|
{
"id": "evt_7f3b19c9e1a5d2b8f4c6e0a3",
"type": "customer.standing.changed",
"created": "2026-10-05T08:03:00.000Z",
"data": {
"object": "customer_standing",
"customerId": "cmg2c0s7t0003cust0001abcd",
"status": "locked",
"reason": "unpaid_invoice",
"reasons": [
"unpaid_invoice"
],
"graceEndsAt": "2026-10-08T07:00:00.000Z",
"lockedSince": "2026-10-08T07:00:00.000Z",
"lockMode": "billing_only",
"rulesEnabled": true,
"rulesApplyFrom": null,
"paidPlan": true,
"hasPaymentMethod": true,
"paymentMethods": {
"cards": 1,
"defaultCard": {
"object": "card",
"id": "cmgcard00001visa4242abcd",
"customerId": "cmg2c0s7t0003cust0001abcd",
"brand": "visa",
"last4": "4242",
"expiryMonth": 12,
"expiryYear": 2028,
"holderName": "T NKOSI",
"isDefault": true,
"status": "active",
"expiring": false,
"source": "card_setup",
"createdAt": "2026-10-05T08:00:00.000Z",
"lastUsedAt": null
},
"debitOrder": false,
"gatewaySubscription": false
},
"outstanding": {
"amount": 299,
"overdueAmount": 299,
"currency": "ZAR",
"invoiceIds": [
"cmg4i5n6v0001inv0001abcd"
],
"invoices": [
{
"id": "cmg4i5n6v0001inv0001abcd",
"number": "INV-000123",
"dueDate": "2026-10-05T07:00:00.000Z",
"balance": 299,
"currency": "ZAR",
"overdue": true,
"paymentPending": false,
"awaitingCollection": false
}
]
},
"links": {
"addCardUrl": null,
"payUrl": null
},
"checkedAt": "2026-10-06T09:00:00.000Z",
"change": "locked",
"previous": {
"status": "grace",
"reason": "unpaid_invoice"
},
"customer": {
"id": "cmg2c0s7t0003cust0001abcd",
"externalReference": "platform-org:42"
}
}
}See the Webhooks guide for setup and signature verification code.