---
title: "List invoices"
description: "Retrieve a paginated list of invoices. Supports filtering by document type, financial status, and date range."
url: https://docs.invoicefalcon.com/api/invoices/list-invoices/
api: "API v1 reference"
method: GET
path: "/invoices"
---

# List invoices

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

Retrieve a paginated list of invoices. Supports filtering by document type, financial status, and date range.

## Query parameters

- `invoice_type` (string): Filter by document type. One of: `invoice`, `quote`, `pro_forma`.
- `financial_status` (string): Filter by payment status. One of: `paid`, `pending`, `partially_paid`, `partially_refunded`, `refunded`, `voided`, `authorized`.
- `created_at_min` (string): Filter invoices created on or after this date (YYYY-MM-DD).
- `created_at_max` (string): Filter invoices created on or before this date (YYYY-MM-DD).
- `page` (integer): Page number.
- `per_page` (integer): Items per page (max 250).

## Returns

- `invoices` (array of objects)
  - `id` (integer): e.g. `48213`
  - `slug` (string): Unique identifier for API calls.
  - `number` (string): Display number (e.g. INV-001).
  - `invoice_type` (string): e.g. `invoice` One of: `invoice`, `quote`, `pro_forma`, `shopify_order`.
  - `total_price` (string): Decimal string.
  - `currency` (string): ISO 4217 code.
  - `financial_status` (string): e.g. `paid`
  - `order_name` (string): Shopify order name (e.g. #1042).
  - `customer_name` (string): e.g. `Jane Doe`
  - `customer_email` (string): e.g. `jane.doe@example.com`
  - `created_at` (string): e.g. `2026-01-15T09:31:12Z`
  - `updated_at` (string): e.g. `2026-01-15T09:31:40Z`
- `meta` (object)
  - `total` (integer): e.g. `3`
  - `page` (integer): e.g. `1`
  - `per_page` (integer): e.g. `25`
  - `total_pages` (integer): e.g. `1`

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

## Examples

### List invoices

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

### List invoices filtered by invoice_type and financial_status

```sh
curl "https://app.invoicefalcon.com/api/v1/external/invoices?invoice_type=invoice&financial_status=paid" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

A paginated list of invoices.

```json
{
  "invoices": [
    {
      "id": 48213,
      "slug": "k7xq2m9d4r",
      "number": "INV-1042",
      "invoice_type": "invoice",
      "total_price": "100.94",
      "currency": "USD",
      "financial_status": "paid",
      "order_name": "#1042",
      "customer_name": "Jane Doe",
      "customer_email": "jane.doe@example.com",
      "created_at": "2026-01-15T09:31:12Z",
      "updated_at": "2026-01-15T09:31:40Z"
    },
    {
      "id": 48190,
      "slug": "p3wz8c1n6t",
      "number": "INV-1041",
      "invoice_type": "invoice",
      "total_price": "58.50",
      "currency": "USD",
      "financial_status": "pending",
      "order_name": "#1041",
      "customer_name": "Sam Rivera",
      "customer_email": "sam.rivera@example.com",
      "created_at": "2026-01-14T09:31:12Z",
      "updated_at": "2026-01-14T09:31:40Z"
    },
    {
      "id": 48177,
      "slug": "d5hb0y7f2e",
      "number": "INV-1040",
      "invoice_type": "invoice",
      "total_price": "240.00",
      "currency": "USD",
      "financial_status": "paid",
      "order_name": "#1040",
      "customer_name": "Alex Chen",
      "customer_email": "alex.chen@example.com",
      "created_at": "2026-01-13T09:31:12Z",
      "updated_at": "2026-01-13T09:31:40Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}
```

## 401

Missing or invalid API key.

```json
{
  "error": "Invalid API key"
}
```

## 403

The store is not on a paid plan. API access requires a paid Invoice Falcon plan.

```json
{
  "error": "REST API access requires a paid plan"
}
```

## 429

Rate limit exceeded. Check `X-RateLimit-Reset` header.

```json
{
  "error": "Rate limit exceeded",
  "retry_after": 30,
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 30 second(s)."
}
```

