List, Get & Cancel Invoices - Numero

List invoices

GET /api/v1/business/invoices

Signature required: Yes

Query param	Type	Default	Description
`status`	string	—	Filter by status (`PENDING`, `PAID`, `CANCELLED`)
`page`	integer	1	Page number
`pageSize`	integer	25	Rows per page

curl "https://api.usenumero.com/numeroaccount/api/v1/business/invoices?status=PENDING&page=1&pageSize=25" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2"

{
  "data": {
    "data": [
      {
        "invoiceNumber": "INV-2024-000123",
        "amount": 25000,
        "currency": "NGN",
        "status": "Pending",
        "customerName": "John Doe"
      }
    ],
    "pageNumber": 1,
    "pageSize": 25,
    "totalCount": 1
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Get an invoice

GET /api/v1/business/invoices/{invoiceNumber}

Signature required: Yes

curl "https://api.usenumero.com/numeroaccount/api/v1/business/invoices/INV-2024-000123" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2"

Returns the full invoice (same shape as Create), including status, paidAmount, paidAt and paidTransactionReference once it’s been funded.

Cancel an invoice

POST /api/v1/business/invoices/{invoiceNumber}/cancel

Signature required: Yes — cancels an unpaid invoice and retires its payment virtual account.

Header	Required	Description
`X-Numero-Api-Key`	Yes	Your API key
`X-Numero-Signature`	Yes	Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing.
`X-Numero-Signature-Version`	Yes	Always `v2`.

curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/invoices/INV-2024-000123/cancel" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2"

{
  "data": true,
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}