---
title: "Get a list of invoices"
method: GET
path: "/api/v1/customers/{id}/invoices"
tags: ["Invoices"]
---

# Get a list of invoices

`GET /api/v1/customers/{id}/invoices`

Retrieves a cursor-paginated list of a customer's invoices, fetched live from the connected billing provider. Ordered by issue date ascending by default; override with orderBy (issueDate | dueDate | total) and orderDir (ASC | DESC). Optionally narrowed to one contract, an issue-date range, and/or a set of invoice states. Returns an empty list when no billing provider is connected or the customer is not synced.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `contractExternalId` string
- `stateIn` string
- `issuedAfter` string, date-time
- `issuedBefore` string, date-time
- `orderBy` 'issueDate' | 'dueDate' | 'total'
- `orderDir` 'ASC' | 'DESC'

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Response `200`

A cursor-paginated list of the customer's invoices.

- InvoiceListResponseDto — A cursor-paginated list of a customer's invoices
  - `data` object[], required
    - `invoiceId` string, required — The billing provider (Received) invoice ID
    - `invoiceExternalId` string, nullable, required — External ID for the invoice: the mapped external ID when one exists, otherwise the invoice ID
    - `invoiceNumber` string, nullable, required — The invoice document number (or draft number while the invoice is unissued)
    - `contractExternalId` string, nullable, required — External ID of the contract the invoice belongs to: your contract ref when mapped, otherwise the Received contract ID
    - `customerExternalId` string, nullable, required — External ID of the customer the invoice belongs to: your customer ref when mapped, otherwise the Received customer ID
    - `state` 'OPEN' | 'CANCELED' | 'PAID', required — The invoice status (open, paid, or canceled)
    - `issueDate` string, date-time, nullable, required — The date the invoice was issued
    - `dueDate` string, date-time, nullable, required — The date payment is due
    - `paidDate` string, date-time, nullable, required — The date the invoice was reconciled as paid; present once reconciled
    - `currency` string, nullable, required — The ISO-4217 currency code of the invoice
    - `subtotal` number, nullable, required — The pre-tax subtotal
    - `tax` number, nullable, required — The total tax amount
    - `discount` number, nullable, required — The total discount amount
    - `total` number, nullable, required — The total amount due
    - `lineItems` object[], required — The invoice line items
      - `description` string, nullable, required — Human-readable description of the line item
      - `quantity` number, nullable, required — Quantity billed on this line
      - `unitPrice` number, nullable, required — Price per unit for this line
      - `amount` number, nullable, required — Total amount for this line (unit price × quantity)
      - `productExternalId` string, nullable, required — External ID of the product this line item relates to, when one is mapped
  - `pagination` object, required — Pagination metadata including cursors for navigating through results
    - `next` string, nullable, required — Cursor for fetching the next page of results, or null if no additional pages exist
    - `prev` string, nullable, required — Cursor for fetching the previous page of results, or null if at the beginning

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `429` — Too many requests.

---

[API](https://skmtc.net/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.net/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stiggio/stigg-api/revisions/3e2c8cfcd035/schema)