# List invoices

Retrieves a paginated list of invoices for the organization associated with the authenticated user.
Organizations can retrieve an account's invoices by passing `x-account-id`, but only for **self-managed** accounts — managed accounts don't have independent billing.

Endpoint: GET /v2/billing/invoices
Version: v2
Security: x-api-key

## Security:

  - `x-api-key` (unknown)
    apiKey in header x-api-key

## Query parameters:

  - `page` (integer)

  - `pageSize` (integer)

## Header parameters:

  - `x-account-id` (integer)
    The ID of an account to perform this request against, instead of the organization tied to the API key.
Only relevant for organizations with accounts; omit this header to act on the organization associated with the authenticated credential.

## Response 200:

  - `200` (unknown)
    Successful response containing a paginated list of invoices.

## Response 200 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: b0eac937-c25c-47a5-bb7e-552f6b860458

  - `status` (string)
    Indicates the status of the request.
    Example: success

  - `data` (object)
    The paginated list of invoices.

  - `data.items` (array)
    Invoices returned for the current page.

  - `data.items.invoiceId` (string)
    Unique identifier for the invoice.
    Example: in_1AeN9DIEQbB48uFlGM6HrtaZ

  - `data.items.date` (string)
    Date on which the invoice was issued.
    Example: 2026-07-01T00:00:00.000000+00:00

  - `data.items.amount` (number)
    Total amount of the invoice in USD.
    Example: 99

  - `data.items.status` (string)
    Current status of the invoice.
    Enum: "paid", "open", "void", "uncollectible"

  - `data.items.receiptNumber` (string)
    Unique number assigned to the receipt.
    Example: BC6E1053-0010

  - `data.items.downloadUrl` (string)
    URL for downloading the invoice.

  - `data.pagination` (object)
    Pagination details for the response.

  - `data.pagination.page` (integer)
    The zero-based page number returned.
    Example: 0

  - `data.pagination.pageSize` (integer)
    The maximum number of items included per page.
    Example: 100

  - `data.pagination.totalItems` (integer)
    The total number of items across all pages.
    Example: 1000

## Response 400:

  - `400` (unknown)
    Error response indicating one or more request parameters are invalid.

## Response 400 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: b0eac937-c25c-47a5-bb7e-552f6b860458

  - `status` (string)
    Indicates the status of the request.
    Example: error

  - `errors` (array)
    Errors that occurred while processing the request.

  - `errors.code` (string)
    Machine-readable error code that identifies the type of error.
    Example: invalid_input

  - `errors.message` (string)
    Human-readable description of the error, including the underlying validation message when available.
    Example: The provided parameter is invalid.

  - `errors.field` (string)
    Name of the request field associated with the error, if applicable.
    Example: name

  - `errors.type` (string)
    Category or context of the error, such as validation or permission.
    Example: validation

## Response 401:

  - `401` (unknown)
    Error response indicating that the API key is missing or invalid.

## Response 401 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: b0eac937-c25c-47a5-bb7e-552f6b860458

  - `status` (string)
    Indicates the status of the request.
    Example: error

  - `errors` (array)
    Errors that occurred while processing the request.

  - `errors.code` (string)
    Machine-readable error code that identifies the type of error.
    Example: invalid_input

  - `errors.message` (string)
    Human-readable description of the error, including the underlying validation message when available.
    Example: The provided parameter is invalid.

  - `errors.field` (string)
    Name of the request field associated with the error, if applicable.
    Example: name

  - `errors.type` (string)
    Category or context of the error, such as validation or permission.
    Example: validation