GET /apiv2/billing/invoices

Your postpaid invoices. At the end of the billing period set in your contract an invoice is issued for the services of that period; each invoice has a due date. Part of postpaid billing.

Endpoints

Endpoint	Returns
GET /apiv2/billing/invoices	all invoices, newest period first
GET /apiv2/billing/invoices/{id}	one invoice with its charges

Request headers

Header	Required	Description
X-API-KEY	yes	API key with the billing.read permission
X-Real-IP	yes	An address from the key whitelist

Example

curl -s 'https://netts.io/apiv2/billing/invoices/12' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10'

{
  "success": true,
  "data": {
    "id": 12,
    "periodStart": "2026-10-12T00:00:00+00:00",
    "periodEnd": "2026-10-19T00:00:00+00:00",
    "totalTrx": "3778.500000",
    "totalUsdc": "1250.400000",
    "paidUsdc": "0.000000",
    "status": "issued",
    "issuedAt": "2026-10-19T00:10:00+00:00",
    "dueAt": "2026-10-24T00:10:00+00:00",
    "charges": [
      {
        "id": 1024,
        "orderId": "AB2EF201B582AA1",
        "productCode": "energy_1h",
        "amountTrx": "1.300000",
        "amountUsdc": "0.430096",
        "status": "invoiced"
      }
    ]
  },
  "timestamp": "2026-10-19T20:31:10+00:00"
}

Each charge has the same fields as in usage; the example shows a few of them.

An invoice

Field	Description
id	the invoice number
periodStart, periodEnd	the billing period the invoice covers, UTC
totalTrx, totalUsdc	the invoice total, in TRX and in the currency of your contract
paidUsdc	how much is already paid, in the currency of your contract
status	issued, delivered, partially_paid, paid or void
issuedAt	when the invoice was issued
dueAt	the date to pay by
charges	only in /invoices/{id}: the charges of the invoice

The list endpoint returns the same fields without charges. An account with no invoices yet gets an empty list.

Errors

HTTP	code	Meaning
401	-1, -2	the key is missing or invalid, or the IP is not whitelisted — answered by the API gateway, see response format
403	billing_read_required, postpaid_required	no permission, or no postpaid billing
404	not_found	no such invoice on your account