---
title: "Retrieve draft"
description: "One Shopify draft order as its page shows it: customer, addresses, line items and totals from Shopify, plus the quote Invoice Falcon made for it, if any. Accepts a gid (gid://shopify/DraftOrder/123), a bare id or the dra"
url: https://docs.invoicefalcon.com/v3-reference/orders/retrieve-draft/
api: "API v3 reference"
method: GET
path: "/orders/drafts/{id}"
---

# Retrieve draft

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

One Shopify draft order as its page shows it: customer, addresses, line items and totals from Shopify, plus the quote Invoice Falcon made for it, if any. Accepts a gid (gid://shopify/DraftOrder/123), a bare id or the draft name (&quot;#D12&quot;). Read-only.

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

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

## Path parameters

- `id` (string, required): A Shopify id (gid://shopify/Order/123 or 123) or the order number as the store shows it (&quot;#1001&quot; or &quot;1001&quot;).

## Returns

- `shopify_draft_order_id` (string): e.g. `gid://shopify/DraftOrder/700`
- `kind` (string): e.g. `draft_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`
- `status` (string): e.g. `open`
- `currency` (string): e.g. `EUR`
- `total` (string): e.g. `120.50`
- `customer` (object)
  - `shopify_customer_id` (string): e.g. `gid://shopify/Customer/42`
  - `name` (string): e.g. `Ann Lee`
  - `email` (string): e.g. `ann@example.com`
  - `phone` (string, nullable)
  - `note` (string, nullable)
  - `default_address` (object, nullable)
- `invoice` (object, nullable)
- `email` (string): e.g. `ann@example.com`
- `phone` (string, nullable)
- `note` (string): e.g. `Gift`
- `cancelled_at` (string, nullable)
- `totals` (object)
  - `subtotal` (string): e.g. `100.00`
  - `shipping` (string): e.g. `10.00`
  - `tax` (string): e.g. `10.50`
  - `discounts` (string): e.g. `0.00`
  - `total` (string): e.g. `120.50`
- `shipping_method` (string): e.g. `Standard`
- `billing_address` (object)
  - `name` (string): e.g. `Ann Lee`
  - `first_name` (string): e.g. `Ann`
  - `last_name` (string): e.g. `Lee`
  - `address1` (string): e.g. `1 Main St`
  - `address2` (string, nullable)
  - `city` (string): e.g. `Berlin`
  - `province` (string, nullable)
  - `province_code` (string, nullable)
  - `country` (string): e.g. `Germany`
  - `country_code` (string): e.g. `DE`
  - `zip` (string): e.g. `10115`
  - `phone` (string, nullable)
- `shipping_address` (object, nullable)
- `line_items` (array of objects)
  - `id` (string): e.g. `gid://shopify/LineItem/9`
  - `title` (string): e.g. `Hat`
  - `variant_title` (string): e.g. `Red`
  - `sku` (string): e.g. `HAT-R`
  - `barcode` (string, nullable)
  - `quantity` (integer): e.g. `2`
  - `unit_price` (string): e.g. `50.00`
  - `total` (string): e.g. `100.00`
  - `image_url` (string, nullable)
  - `selling_plan` (null)
  - `product_id` (string): e.g. `gid://shopify/Product/88`
  - `variant_id` (string): e.g. `gid://shopify/ProductVariant/77`
- `tax_lines` (array of objects)
  - `title` (string): e.g. `VAT`
  - `rate` (number): e.g. `0.19`
  - `amount` (string): e.g. `10.50`
- `documents` (array of anys)

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

## Example request

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

## 200

The requested resource.

```json
{
  "shopify_draft_order_id": "gid://shopify/DraftOrder/700",
  "kind": "draft_order",
  "order_number": "#1001",
  "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": {
    "shopify_customer_id": "gid://shopify/Customer/42",
    "name": "Ann Lee",
    "email": "ann@example.com",
    "phone": null,
    "note": null,
    "default_address": null
  },
  "invoice": null,
  "email": "ann@example.com",
  "phone": null,
  "note": "Gift",
  "cancelled_at": null,
  "totals": {
    "subtotal": "100.00",
    "shipping": "10.00",
    "tax": "10.50",
    "discounts": "0.00",
    "total": "120.50"
  },
  "shipping_method": "Standard",
  "billing_address": {
    "name": "Ann Lee",
    "first_name": "Ann",
    "last_name": "Lee",
    "address1": "1 Main St",
    "address2": null,
    "city": "Berlin",
    "province": null,
    "province_code": null,
    "country": "Germany",
    "country_code": "DE",
    "zip": "10115",
    "phone": null
  },
  "shipping_address": null,
  "line_items": [
    {
      "id": "gid://shopify/LineItem/9",
      "title": "Hat",
      "variant_title": "Red",
      "sku": "HAT-R",
      "barcode": null,
      "quantity": 2,
      "unit_price": "50.00",
      "total": "100.00",
      "image_url": null,
      "selling_plan": null,
      "product_id": "gid://shopify/Product/88",
      "variant_id": "gid://shopify/ProductVariant/77"
    }
  ],
  "tax_lines": [
    {
      "title": "VAT",
      "rate": 0.19,
      "amount": "10.50"
    }
  ],
  "documents": []
}
```

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

## 404

The resource does not exist for this shop, or no action is registered at this path.

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

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

