---
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`

## Request

- Base URL: `https://api.stigg.io`
- URL: `https://api.stigg.io/api/v1/customers/{id}/invoices`
- Auth: API key in header `X-API-KEY`

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.

## Changes

- **2026-07-28** `913f273cc2f7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/stiggio/apis/stigg-api/changes/api/v1/customers/:id/invoices/get.md)

---

[API](https://skmtc.dev/stiggio/apis/stigg-api.md) - [All operations](https://skmtc.dev/stiggio/apis/stigg-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stiggio/apis/stigg-api/revisions/3e2c8cfcd035?raw)