---
title: "List invoices"
description: "The invoices the V3 Invoices page lists, newest first, as list rows (number, order, customer, financial status, total, sent / printed / reminder timestamps). Invoices only by default; pass document_type to list quotes, c"
url: https://docs.invoicefalcon.com/v3-reference/documents/list-invoices/
api: "API v3 reference"
method: GET
path: "/documents/invoices"
---

# List invoices

`GET https://app.invoicefalcon.com/api/v3/external/documents/invoices`

The invoices the V3 Invoices page lists, newest first, as list rows (number, order, customer, financial status, total, sent / printed / reminder timestamps). Invoices only by default; pass document_type to list quotes, credit notes or pro forma invoices from the same table. Trashed invoices are left out unless link=trashed. Read-only.

`document_type` values: `invoice` (Invoice), `quote` (Quote), `credit_note` (Credit note), `pro_forma` (Pro forma invoice), `custom` (Custom invoice).

`financial_status` values: `pending` (Payment pending), `authorized` (Authorized), `partially_paid` (Partially paid), `paid` (Paid), `partially_refunded` (Partially refunded), `refunded` (Refunded), `voided` (Voided), `expired` (Expired), `cancelled` (Cancelled).

`link` values: `linked` (Created from a Shopify order), `not_linked` (Standalone (no Shopify order)), `trashed` (In the trash).

## Query parameters

- `document_type` (string): Which documents: 'invoice' (default), 'quote', 'credit_note', 'pro_forma', 'custom'. One of: `invoice` (Invoice), `quote` (Quote), `credit_note` (Credit note), `pro_forma` (Pro forma invoice), `custom` (Custom invoice). One of: `invoice`, `quote`, `credit_note`, `pro_forma`, `custom`.
- `link` (string): 'linked' (created from a Shopify order), 'not_linked' (standalone) or 'trashed'. One of: `linked` (Created from a Shopify order), `not_linked` (Standalone (no Shopify order)), `trashed` (In the trash). One of: `linked`, `not_linked`, `trashed`.
- `sort` (string): 'created_at desc' (default) or 'created_at asc'. One of: `created_at desc`, `created_at asc`.
- `page` (integer): 1-based page number.
- `per_page` (integer): Rows per page, default 25, max 100.
- `financial_status` (string): Shopify financial status of the order, one or many ('paid', 'pending,partially_paid'). One of: `pending` (Payment pending), `authorized` (Authorized), `partially_paid` (Partially paid), `paid` (Paid), `partially_refunded` (Partially refunded), `refunded` (Refunded), `voided` (Voided), `expired` (Expired), `cancelled` (Cancelled). One of: `pending`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded`, `voided`, `expired`, `cancelled`.
- `from` (string): Created on or after this date (ISO 8601).
- `to` (string): Created on or before this date (ISO 8601).
- `order_id` (string): The Shopify order, as a gid (gid://shopify/Order/123) or a bare number.
- `q` (string): Free text over invoice number, order name, customer name and email.

## Returns

- `items` (array of objects, required)
  - `id` (integer): e.g. `980191068`
  - `document_type` (string): e.g. `invoice`
  - `invoice_number` (string): e.g. `#1001`
  - `title` (string): e.g. `Invoice`
  - `order` (object)
    - `shopify_order_id` (string): e.g. `gid://shopify/Order/12213474623569`
    - `name` (string): e.g. `#1001`
    - `number` (integer): e.g. `1001`
  - `customer` (object)
    - `id` (integer): e.g. `43`
    - `name` (string): e.g. `Customer 1`
    - `email` (string): e.g. `cus1@gmail.com`
  - `financial_status` (string): e.g. `paid`
  - `currency` (string): e.g. `USD`
  - `total` (string): e.g. `1100.22`
  - `issued_on` (string): e.g. `2025-12-11`
  - `due_on` (string, nullable)
  - `sent_at` (string, nullable)
  - `printed_at` (string, nullable)
  - `reminder_sent_at` (string, nullable)
  - `paid` (boolean): e.g. `true`
  - `edited` (boolean): e.g. `false`
  - `trashed` (boolean): e.g. `true`
  - `e_invoice_status` (string, nullable)
  - `created_at` (string): e.g. `2026-11-10T09:41:43Z`
- `page` (object, required): Offset paging of a list (`page`, `per_page` query params).
  - `number` (integer, required): 1-based page number.
  - `size` (integer, required): Rows per page, max 100.
  - `total` (integer, required): Rows across all pages.
  - `total_pages` (integer, required): e.g. `1`

Rate limit: this call costs 1 point ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Examples

### List invoices

```sh
curl "https://app.invoicefalcon.com/api/v3/external/documents/invoices" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

### List invoices filtered by document_type, link and sort

```sh
curl "https://app.invoicefalcon.com/api/v3/external/documents/invoices?document_type=invoice&link=linked&sort=created_at%20desc" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

One page of rows.

```json
{
  "items": [
    {
      "id": 980191068,
      "document_type": "invoice",
      "invoice_number": "#1001",
      "title": "Invoice",
      "order": {
        "shopify_order_id": "gid://shopify/Order/12213474623569",
        "name": "#1001",
        "number": 1001
      },
      "customer": {
        "id": 43,
        "name": "Customer 1",
        "email": "cus1@gmail.com"
      },
      "financial_status": "paid",
      "currency": "USD",
      "total": "1100.22",
      "issued_on": "2025-12-11",
      "due_on": null,
      "sent_at": null,
      "printed_at": null,
      "reminder_sent_at": null,
      "paid": true,
      "edited": false,
      "trashed": true,
      "e_invoice_status": null,
      "created_at": "2026-11-10T09:41:43Z"
    }
  ],
  "page": {
    "number": 1,
    "size": 25,
    "total": 1,
    "total_pages": 1
  }
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

