---
title: "List drafts"
description: "The Shopify draft orders as the Draft orders tab lists them, newest first, each with the quote Invoice Falcon made for it (number, when it was sent, printed or downloaded) or invoice: null. Filters: draft status (open, i"
url: https://docs.invoicefalcon.com/v3-reference/orders/list-drafts/
api: "API v3 reference"
method: GET
path: "/orders/drafts"
---

# List drafts

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

The Shopify draft orders as the Draft orders tab lists them, newest first, each with the quote Invoice Falcon made for it (number, when it was sent, printed or downloaded) or `invoice: null`. Filters: draft status (open, invoice_sent, completed), a created date range and a free-text search. Pages by Shopify cursor. Read-only.

`status` values: `open` (Open), `invoice_sent` (Invoice sent), `completed` (Completed).

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

## 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).
- `status` (string): Draft status filter: open, invoice_sent, completed. One of: `open` (Open), `invoice_sent` (Invoice sent), `completed` (Completed). One of: `open`, `invoice_sent`, `completed`.

## Returns

- `items` (array of objects, required)
  - `shopify_draft_order_id` (string): e.g. `gid://shopify/DraftOrder/700`
  - `kind` (string): e.g. `draft_order`
  - `order_number` (string): e.g. `#D1`
  - `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`
  - `status` (string): e.g. `open`
  - `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. `980191038`
    - `type` (string): e.g. `quote`
    - `number` (string): e.g. `Q-1`
    - `created_at` (string): e.g. `2026-11-10T09:24:20Z`
    - `sent_at` (string, nullable)
    - `printed_at` (string, nullable)
    - `downloaded_at` (string, nullable)
    - `reminder_sent_at` (string, nullable)
  - `cursor` (string): e.g. `cur700`
- `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. `false`
  - `has_previous_page` (boolean, required): e.g. `false`
  - `start_cursor` (string, nullable)
  - `end_cursor` (string, nullable)
  - `total` (integer, nullable): e.g. `1`

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

## Examples

### List drafts

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

### List drafts filtered by status

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

## 200

One page of rows.

```json
{
  "items": [
    {
      "shopify_draft_order_id": "gid://shopify/DraftOrder/700",
      "kind": "draft_order",
      "order_number": "#D1",
      "created_at": "2026-03-01T10:00:00Z",
      "processed_at": "2026-03-01T10:00:00Z",
      "financial_status": "paid",
      "status": "open",
      "currency": "EUR",
      "total": "120.50",
      "customer": {
        "name": "Ann Lee",
        "email": "ann@example.com"
      },
      "invoice": {
        "id": 980191038,
        "type": "quote",
        "number": "Q-1",
        "created_at": "2026-11-10T09:24:20Z",
        "sent_at": null,
        "printed_at": null,
        "downloaded_at": null,
        "reminder_sent_at": null
      },
      "cursor": "cur700"
    }
  ],
  "page": {
    "size": 25,
    "has_next_page": false,
    "has_previous_page": false,
    "start_cursor": null,
    "end_cursor": null,
    "total": 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"
}
```

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

