API reference
Billing
Invoices and the prepaid wallet.
Try these requests in Postman: Download Postman collection (how to use it).
- List invoices
GET /v1/invoices - Retrieve an invoice
GET /v1/invoices/{id} - Retrieve the wallet
GET /v1/wallet
List invoices
GET/v1/invoices
periodStart / periodEnd: the billing period the invoice covers (null for one-off items such as AI credits). Periods are half-open: periodEnd is the first instant after the period.
Requires a secret key with the read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | Items per page, 1-100 (default 50). |
offset | query | integer | Items to skip (default 0). |
status | query | string | UNPAID, PAID or VOID. |
Request
curl "https://api.newhost.co.za/v1/invoices" \
-H "Authorization: Bearer sk_live_..."Response
{
"data": [
{
"id": "clx8inv0001",
"number": "NH-2026-000123",
"kind": "PLAN",
"status": "PAID",
"amount": "99.99",
"vat": "0.00",
"issuedAt": "2026-09-01T08:00:00.000Z",
"dueAt": "2026-09-08T08:00:00.000Z",
"paidAt": "2026-09-01T08:02:11.000Z",
"periodStart": "2026-09-01T08:02:11.000Z",
"periodEnd": "2026-10-01T08:02:11.000Z"
}
],
"has_more": false
}Retrieve an invoice
GET/v1/invoices/{id}
Each line has a short description, the amount, a longer details text and the period it bills (periodStart / periodEnd, when it has one). Lines priced gross (website aliases) also carry gross and vat. Global Software Services (Pty) Ltd, the company behind NewHost, is not registered for VAT, so no VAT is added: vat is "0.00" and amount is the full amount you pay.
Requires a secret key with the read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | The invoice ID. |
Request
curl "https://api.newhost.co.za/v1/invoices/ID" \
-H "Authorization: Bearer sk_live_..."Response
{
"data": {
"id": "clx8inv0001",
"number": "NH-2026-000123",
"kind": "PLAN",
"status": "PAID",
"amount": "349.99",
"vat": "0.00",
"issuedAt": "2026-09-01T08:00:00.000Z",
"dueAt": "2026-09-08T08:00:00.000Z",
"paidAt": "2026-09-01T08:02:11.000Z",
"periodStart": "2026-09-01T08:02:11.000Z",
"periodEnd": "2026-10-01T08:02:11.000Z",
"lines": [
{
"description": "Starter hosting plan (monthly)",
"amount": "99.99",
"details": "Starter app hosting, billed monthly. Includes 1 app, 512 MB RAM, 5 GB storage, 1 database, 100 GB traffic. Period 1 Sep 2026 – 30 Sep 2026.",
"periodStart": "2026-09-01T08:02:11.000Z",
"periodEnd": "2026-10-01T08:02:11.000Z"
},
{
"description": "Website alias: example.com (September 2026)",
"amount": "250.00",
"gross": "250.00",
"vat": "0.00",
"details": "R250.00 per alias per month, 1 month. Period 1 Sep 2026 – 30 Sep 2026.",
"periodStart": "2026-09-01T08:02:11.000Z",
"periodEnd": "2026-10-01T08:02:11.000Z"
}
]
}
}Retrieve the wallet
GET/v1/wallet
Requires a secret key with the read scope.
Request
curl "https://api.newhost.co.za/v1/wallet" \
-H "Authorization: Bearer sk_live_..."Response
{
"data": {
"balance": "250.00",
"autoTopUpEnabled": false,
"transactions": [
{
"amount": "250.00",
"balanceAfter": "250.00",
"type": "TOPUP",
"description": "Wallet top-up",
"createdAt": "2026-09-01T08:00:00.000Z"
}
]
}
}