List invoices

Time	Status	User Agent
Retrieving recent requests…

Retrieve a paginated list of invoices that the authenticated user has access to.

Endpoint

GET /2.0/invoices

Query Parameters

Pagination & Sorting

Parameter	Type	Default	Description
`limit`	number	`100`	Number of results per page
`page`	number	`1`	Page number (1-based)
`sort`	string	-	Sort field and direction. Format: `field:asc` or `field:desc` (e.g. `values.invoiceDate:desc`)

Filters

Any field listed in the Invoice object can be used as a query parameter to filter results. Only fields returned in the API response can be used for filtering.

Date range filters: Date fields support range operators using dot notation:

field.gte - Greater than or equal to
field.lte - Less than or equal to
field.gt - Greater than
field.lt - Less than

Example: values.invoiceDate.gte=2024-01-01&values.invoiceDate.lte=2024-12-31

Common filters:

Parameter	Type	Description
`status`	string	Filter by processing status: `processing`, `pending`, `uploading`, `queued`, `captured`, `error`, `completed`
`financialStatus`	string	Filter by financial status: `approved`, `new`, `not-approved`, `paid`, `sent-for-payment`
`completed`	boolean	Filter by completion status
`isPaid`	boolean	Filter by payment status
`accountId`	string	Filter by account (meter) ID
`entityId`	string	Filter by entity ID
`supplierId`	string	Filter by supplier ID
`tags`	string	Filter by tag
`type`	string	Filter by invoice type

Response

{
  "total": 200,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "fileName": "invoice-2024-01.pdf",
      "status": "completed",
      "financialStatus": "approved",
      "completed": true,
      "isPaid": true,
      "values": {
        "invoiceNumber": "INV-2024-001",
        "supplierName": "British Gas",
        "invoiceDate": "2024-01-15T00:00:00.000Z",
        "startDate": "2024-01-01T00:00:00.000Z",
        "endDate": "2024-01-31T00:00:00.000Z",
        "totalUnits": 15000,
        "totalUnitCost": 1500.00,
        "totalDaily": 45.50,
        "totalCCL": 120.00,
        "netTotalCost": 1665.50,
        "totalTax": 333.10,
        "totalCost": 1998.60,
        "units": "kwh",
        "meterPointNumber": "1234567890123",
        "startRead": "45000",
        "endRead": "60000"
      },
      "rates": [
        {
          "rateName": "Day Rate",
          "consumption": 10000,
          "unitRate": 0.12,
          "cost": 1200.00,
          "units": "kwh"
        },
        {
          "rateName": "Night Rate",
          "consumption": 5000,
          "unitRate": 0.06,
          "cost": 300.00,
          "units": "kwh"
        }
      ],
      "accountId": "507f1f77bcf86cd799439012",
      "entityId": "507f1f77bcf86cd799439013",
      "supplierId": "507f1f77bcf86cd799439014",
      "createdAt": "2024-02-01T09:30:00.000Z",
      "updatedAt": "2024-02-05T14:15:00.000Z"
    }
  ]
}

Example Request

curl -X GET "https://api.etainabl.com/2.0/invoices?status=completed&financialStatus=approved&accountId=507f1f77bcf86cd799439012&limit=50&sort=values.invoiceDate:desc" \
  -H "x-api-key: YOUR_API_KEY"

Scope Required

read:invoices