---
title: "List Invoices"
method: GET
path: "/invoices"
tags: ["Invoices"]
---

# List Invoices

`GET /invoices`

## Request

- Base URL: `https://api.upflow.io/v1`
- URL: `https://api.upflow.io/v1/invoices`
- Auth: API key in header `X-Api-Key` and API key in header `X-Api-Secret`

List invoices with optional filtering.

## Query parameters

- `offset` integer
- `page` integer
- `limit` integer
- `customer.id` string
- `customer.externalId` string
- `updatedAt` RangeQueryUpdateSpecs: Only return entities that were updated during the given date range. (ISO 8601 format)
  - `updatedAt.gt` string, date-time: Minimum value to filter by (exclusive)
  - `updatedAt.gte` string, date-time: Minimum value to filter by (inclusive)
  - `updatedAt.lt` string, date-time: Maximum value to filter by (exclusive)
  - `updatedAt.lte` string, date-time: Maximum value to filter by (inclusive)
- `customId` string
- `dunningPlanId` string
- `state` 'DUE' | 'OVERDUE' | 'PAID' | 'WRITTEN_OFF' | 'DISPUTED': Status of the invoice.
- `sortBy` 'customId' | 'updatedAt'
- `sortOrder` 'DESC' | 'ASC'

## Response `200`

Paginated list of invoices.

- object
  - `offset` integer: 0-based index of the first item returned. Returned when using offset-based pagination or by default.
  - `page` integer: Page number (1-based). Returned when using page-based pagination.
  - `limit` integer, required: Maximum number of items returned.
  - `total` integer, required: Total items in the set.
  - `invoices` Invoice[], required
    - `externalId` string: Invoice external identifier.
    - `issuedAt` string, date-time: The date at which the invoice was issued (ISO 8601 format).
    - `dueDate` string, date-time: The date when the invoice is due (ISO 8601 format).
    - `name` string: The invoice name or description.
    - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
    - `grossAmount` integer, required: Amount including taxes (in cents).
    - `netAmount` integer, required: Amount net of taxes (in cents).
    - `amountOutstanding` integer, required: Amount currently outstanding on the invoice (in cents).
    - `dunningPlanId` string, uuid, nullable: Dunning plan ID associated with the invoice.
    - `id` string, uuid, required: The Invoice ID.
    - `customerId` string, uuid, nullable: Customer ID associated with the invoice.
    - `payments` PaymentsObject[]: List of payments associated with the invoice.
      - `id` string, uuid: The Payment ID.
      - `amount` integer: Amount of payment (in cents).
      - `linkedAmount` integer: Amount of the payment allocated to this invoice (in cents).
      - `executedAt` string, date-time: Payment execution date (ISO 8601 format).
      - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
    - `pdfUrl` string, uri, nullable: URL to the invoice PDF.
    - `state` 'DUE' | 'OVERDUE' | 'PAID' | 'WRITTEN_OFF' | 'DISPUTED', required: Status of the invoice.
    - `customFields` CustomFieldValue[]: List of invoice's custom fields with values.
      - `id` string, uuid, required: The Custom Field ID.
      - `label` string, required: Custom field label displayed in the UI.
      - `dataType` 'STRING' | 'BOOLEAN' | 'FLOAT' | 'DATE' | 'DATETIME' | 'SELECT' | 'MULTI_SELECT', required: Data type of the custom field.
      - `source` string, nullable, required: Source of the custom field value.
      - `value` union, required: The value of the custom field. Can be a primitive (string, integer, boolean), a single object for SELECT types, an array of objects for MULTI_SELECT types.
        - integer: Integer value.
        - string: String value (could also be date-time or date).
        - boolean: Boolean value.
        - CustomFieldValueOption
          - `externalId` string, nullable: External identifier for the option.
          - `label` string, required: Display label for the option.
        - CustomFieldValueOption[]: Value for MULTI_SELECT type.
          - `externalId` string, nullable: External identifier for the option.
          - `label` string, required: Display label for the option.
    - `dunningPaused` boolean: Whether dunning is currently paused for this invoice.
    - `dunningPausedUntil` string, date, nullable: The date until which dunning is paused (YYYY-MM-DD), or `null` if not paused.
    - `dunningPausedComment` string, nullable: Comment provided when dunning was paused, or `null` if none.
    - `dunningPausedByUserId` string, uuid, nullable: The ID of the user who paused dunning, or `null` if not paused.
    - `promiseToPay` InvoicePromiseToPay, nullable: The promise to pay currently set on the invoice, or `null` if there is none.
      - `expectedDate` string, date, required: Expected payment date (YYYY-MM-DD).
      - `comment` string, nullable, required: Comment related to the promise to pay, or `null` if none was provided.
      - `isActive` boolean, required: Whether the promise to pay is still active.
      - `createdAt` string, date-time, required: The date at which the promise to pay was created (ISO 8601 format).
    - `createdAt` string, date-time: The date at which the invoice was created (ISO 8601 format).
    - `updatedAt` string, date-time: The date at which the invoice was last updated (ISO 8601 format).

---

[API](https://skmtc.dev/upflow/apis/upflow-api.md) - [All operations](https://skmtc.dev/upflow/apis/upflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upflow/apis/upflow-api/revisions/898a98ca0587?raw)