NewHost Docs

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

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

NameInTypeDescription
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).
statusquerystringUNPAID, 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

NameInTypeDescription
idrequiredpathstringThe 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"
      }
    ]
  }
}

Next: Webhooks →