---
title: "List orders"
description: "The Shopify orders of the store as the Orders page lists them, newest first, each with the Invoice Falcon invoice that exists for it (number, when it was sent, printed or downloaded, e-invoice state) or invoice: null whe"
url: https://docs.invoicefalcon.com/v3-reference/orders/list-orders/
api: "API v3 reference"
method: GET
path: "/orders"
---

# List orders

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

The Shopify orders of the store as the Orders page lists them, newest first, each with the Invoice Falcon invoice that exists for it (number, when it was sent, printed or downloaded, e-invoice state) or `invoice: null` when none was made yet. Filters match the page: payment status, fulfillment status, a created date range and a free-text search. Pages by Shopify cursor: pass `page.end_cursor` as `after` for the next page. Read-only; it never creates invoices.

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

`fulfillment_status` values: `fulfilled` (Fulfilled), `unfulfilled` (Unfulfilled), `partially_fulfilled` (Partially fulfilled), `in_progress` (In progress), `on_hold` (On hold), `pending_fulfillment` (Pending), `scheduled` (Scheduled), `restocked` (Restocked).

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

`invoice.e_invoice.status` values: `generated` (E-invoice embedded), `fallback` (Standard PDF), `requested` (Requested).

## Query parameters

- `per_page` (integer): Rows per page, 1-100 (default 25).
- `after` (string): Cursor of the last row of the previous page (page.end_cursor), to go forward.
- `before` (string): Cursor of the first row of the next page (page.start_cursor), to go back.
- `q` (string): Free text, in Shopify order search syntax: an order number (&quot;#1001&quot;), a customer name or email, or a field filter (&quot;tag:wholesale&quot;, &quot;sku:ABC&quot;).
- `created_at_min` (string): Only orders created on or after this date (YYYY-MM-DD, shop time zone).
- `created_at_max` (string): Only orders created on or before this date (YYYY-MM-DD, shop time zone).
- `financial_status` (string): Payment status filter: paid, pending, refunded, partially_paid, authorized, voided. One of: `paid` (Paid), `pending` (Pending), `refunded` (Refunded), `partially_paid` (Partially paid), `partially_refunded` (Partially refunded), `authorized` (Authorized), `voided` (Voided), `expired` (Expired). One of: `paid`, `pending`, `refunded`, `partially_paid`, `partially_refunded`, `authorized`, `voided`, `expired`.
- `fulfillment_status` (string): Fulfillment filter: shipped, unshipped, partial, in_progress, on_hold (shipped = fulfilled, unshipped = unfulfilled). One of: `fulfilled` (Fulfilled), `unfulfilled` (Unfulfilled), `partially_fulfilled` (Partially fulfilled), `in_progress` (In progress), `on_hold` (On hold), `pending_fulfillment` (Pending), `scheduled` (Scheduled), `restocked` (Restocked). One of: `fulfilled`, `unfulfilled`, `partially_fulfilled`, `in_progress`, `on_hold`, `pending_fulfillment`, `scheduled`, `restocked`.

## Returns

- `items` (array of objects, required)
  - `shopify_order_id` (string): e.g. `gid://shopify/Order/5551001`
  - `kind` (string): e.g. `order`
  - `order_number` (string): e.g. `#1001`
  - `created_at` (string): e.g. `2026-03-01T10:00:00Z`
  - `processed_at` (string): e.g. `2026-03-01T10:00:00Z`
  - `financial_status` (string): e.g. `paid`
  - `fulfillment_status` (string): e.g. `fulfilled`
  - `currency` (string): e.g. `EUR`
  - `total` (string): e.g. `120.50`
  - `customer` (object)
    - `name` (string): e.g. `Ann Lee`
    - `email` (string): e.g. `ann@example.com`
  - `invoice` (object)
    - `id` (integer): e.g. `980191045`
    - `type` (string): e.g. `invoice`
    - `number` (string): e.g. `INV-77`
    - `created_at` (string): e.g. `2026-11-10T09:24:21Z`
    - `sent_at` (string): e.g. `2026-03-02T10:00:00Z`
    - `printed_at` (string): e.g. `2026-03-03T10:00:00Z`
    - `downloaded_at` (string, nullable)
    - `reminder_sent_at` (string, nullable)
    - `e_invoice` (object)
      - `status` (object, nullable)
      - `error` (string, nullable)
      - `requested` (boolean): e.g. `false`
  - `cursor` (string): e.g. `cur5551001`
- `page` (object, required): Cursor paging of a Shopify-backed list: pass `end_cursor` as `after` for the next page.
  - `size` (integer, required): e.g. `25`
  - `has_next_page` (boolean, required): e.g. `true`
  - `has_previous_page` (boolean, required): e.g. `false`
  - `start_cursor` (string, nullable): e.g. `a`
  - `end_cursor` (string, nullable): e.g. `z`
  - `total` (integer, nullable): e.g. `2`

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

## Examples

### List orders

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

### List orders filtered by financial_status and fulfillment_status

```sh
curl "https://app.invoicefalcon.com/api/v3/external/orders?financial_status=paid&fulfillment_status=fulfilled" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

One page of rows.

```json
{
  "items": [
    {
      "shopify_order_id": "gid://shopify/Order/5551001",
      "kind": "order",
      "order_number": "#1001",
      "created_at": "2026-03-01T10:00:00Z",
      "processed_at": "2026-03-01T10:00:00Z",
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "currency": "EUR",
      "total": "120.50",
      "customer": {
        "name": "Ann Lee",
        "email": "ann@example.com"
      },
      "invoice": {
        "id": 980191045,
        "type": "invoice",
        "number": "INV-77",
        "created_at": "2026-11-10T09:24:21Z",
        "sent_at": "2026-03-02T10:00:00Z",
        "printed_at": "2026-03-03T10:00:00Z",
        "downloaded_at": null,
        "reminder_sent_at": null,
        "e_invoice": {
          "status": null,
          "error": null,
          "requested": false
        }
      },
      "cursor": "cur5551001"
    },
    {
      "shopify_order_id": "gid://shopify/Order/5551002",
      "kind": "order",
      "order_number": "#1002",
      "created_at": "2026-03-01T10:00:00Z",
      "processed_at": "2026-03-01T10:00:00Z",
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "currency": "EUR",
      "total": "120.50",
      "customer": {
        "name": "Ann Lee",
        "email": "ann@example.com"
      },
      "invoice": null,
      "cursor": "cur5551002"
    }
  ],
  "page": {
    "size": 25,
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "a",
    "end_cursor": "z",
    "total": 2
  }
}
```

## 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"
}
```

## 502

Shopify did not answer or returned an error (`shopify_error`). Retry later.

```json
{
  "errors": [
    "Shopify did not return the orders: no response"
  ],
  "code": "shopify_error"
}
```

