DraftOrder

Version 2019-04 (latest)

You can use the DraftOrder resource to allow merchants to create orders on behalf of customers. This is useful for Shopify merchants who receive orders through outside channels and enables a wide range of use cases including the following:

  • Create new orders for sales made by phone, in person, via chat, or by other means. Credit card payments for these orders can subsequently be entered in the Shopify admin.
  • Send invoices to customers to pay with a secure checkout link.
  • Use custom items to represent additional costs or products that aren't displayed in a shop's inventory.
  • Re-create mistaken orders.
  • Sell products at discount or wholesale rates.
  • Take pre-orders.

What you can do with DraftOrder

The Shopify API lets you do the following with the DraftOrder resource. More detailed versions of these general actions may be available:

DraftOrder properties

id
"id": 450789469

The ID of the draft order.

order_id
"id": 456789101

The ID of the order that 's created and associated with the draft order after the draft order is completed.

name
"name": "#1001"

Name of the draft order.

customer
"customer": {
  "id": 207119551,
  "email": "bob.norman@hostmail.com",
  "accepts_marketing": false,
  "created_at": "2012-03-13T16:09:55-04:00",
  "updated_at": "2012-03-13T16:09:55-04:00",
  "first_name": "Bob",
  "last_name": "Norman",
  "orders_count": "1",
  "state": "disabled",
  "total_spent": "0.00",
  "last_order_id": 450789469,
  "note": null,
  "verified_email": true,
  "multipass_identifier": null,
  "tax_exempt": false,
  "phone": "+13125551212",
  "tags": "loyal",
  "last_order_name": "#1001",
  "currency": "USD",
  "addresses": {},
  "admin_graphql_api_id": "gid://shopify/Customer/207119551",
  "default_address": {}
}

Information about the customer. To load a customer, provide the ID as part of the draft order object in the Create POST request. To remove a customer, set the customer property to null as part of the Create POST request. For more information, see Loading and removing customers. For more information about the customer object, see the Customer resource.

shipping_address
"shipping_address": {
  "address1": "123 Amoebobacterieae St",
  "address2": "",
  "city": "Ottawa",
  "company": null,
  "country": "Canada",
  "first_name": "Bob",
  "last_name": "Bobsen",
  "latitude": "45.41634",
  "longitude": "-75.6868",
  "phone": "555-625-1199",
  "province": "Ontario",
  "zip": "K2P0V6",
  "name": "Bob Bobsen",
  "country_code": "CA",
  "province_code": "ON"
}

The mailing address to where the order will be shipped. This address is optional and will not be available on orders that do not require shipping. It has the following properties:

  • address1: The street address of the shipping address.
  • address2: An optional additional field for the street address of the shipping address.
  • city: The city of the shipping address.
  • company: The company of the person associated with the shipping address.
  • country: The name of the country of the shipping address.
  • country_code: The two-letter code for the country of the shipping address.
  • first_name: The first name of the person associated with the payment method.
  • last_name: The last name of the person associated with the payment method.
  • latitude: The latitude of the shipping address.
  • longitude: The longitude of the shipping address.
  • name: The full name of the person associated with the payment method.
  • phone: The phone number at the shipping address.
  • province: The name of the state or province of the shipping address.
  • province_code: The two-letter abbreviation of the state or province of the shipping address.
  • zip: The zip or postal code of the shipping address.
billing_address
"billing_address": {
  "address1": "123 Amoebobacterieae St",
  "address2": "",
  "city": "Ottawa",
  "company": null,
  "country": "US",
  "first_name": null,
  "id": 207119551,
  "last_name": null,
  "phone": "(555)555-5555",
  "province": "KY",
  "zip": "40202",
  "name": null,
  "province_code": null,
  "country_code": null,
  "default": true
}

The mailing address associated with the payment method. This address is an optional field that won't be available on orders that do not require a payment method. It has the following properties:

  • address1: The street address of the billing address.
  • address2: An optional additional field for the street address of the billing address.
  • city: The city of the billing address.
  • company: The company of the person associated with the billing address.
  • country: The name of the country of the billing address.
  • country_code: The two-letter code (ISO 3166-1 alpha-2 two-letter country code) for the country of the billing address.
  • first_name: The first name of the person associated with the payment method.
  • last_name: The last name of the person associated with the payment method.
  • latitude: The latitude of the billing address.
  • longitude: The longitude of the billing address.
  • name: The full name of the person associated with the payment method.
  • phone: The phone number at the billing address.
  • province: The name of the billing address region, such as province, state, or prefecture.
  • province_code: The two-letter abbreviation of the region for the billing address.
  • zip: The postal code of the billing address, such as zip, postcode, or Eircode.
note
"note": null

The text of an optional note that a shop owner can attach to the draft order.

note_attributes
"note_attributes": [
  {
    "name": "custom name",
    "value": "custom value"
  }
]

Extra information that is added to the order. Appears in the Additional details section of an order details page. Each array entry must contain a hash with name and value keys.

email
"email": "bob.norman@example.com"

The customer's email address.

currency
"currency": "USD"

The three letter code (ISO 4217 format) for the currency used for the payment.

invoice_sent_at
"invoice_sent_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the invoice was emailed to the customer.

invoice_url
"invoice_url": "https://www.example.com/14376108/checkouts/91a9b3f92d7d42e57268eff5ebd570df"

The URL for the invoice.

line_items
"line_items": {
  "custom": false,
  "fulfillable_quantity": 1,
  "fulfillment_service": "amazon",
  "grams": 500,
  "id": 669751112,
  "price": "199.99",
  "product_id": 7513594,
  "quantity": 1,
  "requires_shipping": true,
  "sku": "IPOD-342-N",
  "title": "IPod Nano",
  "variant_id": 4264112,
  "variant_title": "Pink",
  "vendor": "Apple",
  "name": "IPod Nano - Pink",
  "gift_card": false,
  "properties": [
    {
      "name": "custom engraving",
      "value": "Happy Birthday Mom!"
    }
  ],
  "taxable": true,
  "tax_lines": [
    {
      "title": "title of tax line",
      "rate": "10",
      "price": "18"
    }
  ],
  "applied_discount": [
    {
      "title": "title of the discount",
      "description": "Description of discount!",
      "value": "10",
      "value_type": "percentage",
      "amount": "19.99"
    }
  ]
}

Product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Each line_item object has the following properties:

  • custom: Read only field Whether this is a custom line item or a product variant line item. If set to true indicates a custom line item. If set to false indicates a product variant line item.
  • id: The ID of the line item.
  • variant_id: The ID of the product variant ID corresponding to the line item. Required for a product variant line item. Set to null for a custom line item.
  • product_id: The ID of the product corresponding to the line item’s product variant.
  • name: The name of the product.
  • variant_title: The title of the product variant. Defaults to Custom for custom line items created via the API.
  • vendor: Vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values are true or false.
  • fulfillment_service: Service provider responsible for fulfillment. Valid values are either manual or the name of the provider. eg amazon, shipwire, etc. Defaults to manual for custom line items.
  • properties: An array of custom information for an item that has been added to the draft order, often used to provide product customization options. Copied to created order when draft order is completed.
  • applied_discount: The discount applied to the line item. For more information, see applied_discount.
  • tax_line: The calculated rate and amount of taxes. For more information, see tax_lines.
  • title: The title of the product or variant. Only applicable to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Only applicable to custom line items. Required field.
  • grams: Weight in grams. Only applicable to custom line items. If not specified, defaults to 0.
  • requires_shipping: Whether the fulfillment requires shipping. Applicable only to custom line items. Valid values are true or false.
  • sku: A unique identifier of the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Only applicable to custom line items.
shipping_line
"shipping_line": {
  "handle": "shopify-Standard%20Shipping-8.00",
  "price": 0.0,
  "title": "Free Shipping"
}

A shipping_line object, which details the shipping method used. The object has the following properties:

  • custom: Whether this is a regular shipping line or custom shipping line.
  • handle: The handle of the shipping rate which was selected and applied. Required for regular shipping lines.
  • title: The title of the shipping method. Required for custom shipping lines. (maximum: 255 characters)
  • price: The price of the shipping method. Required for custom shipping lines.
tags
"tags": "tagsational"

A comma-seperated list of additional short descriptors, commonly used for filtering and searching. Each individual tag is limited to 40 characters in length. For example, tags: "tag1","tag2","tag3".

tax_exempt
"tax_exempt": false

Whether taxes are exempt for the draft order. If set to false, then Shopify refers to the taxable field for each line_item. If a customer is applied to the draft order, then Shopify uses the customer's tax_exempt field instead.

tax_lines
"tax_lines": [
  {
    "price": 11.94,
    "rate": 0.06,
    "title": "State Tax"
  }
]

An array of tax line objects, each of which details a tax applicable to the order. Each object has the following properties:

  • price: The amount of tax to be charged.
  • rate: The rate of tax to be applied.
  • title: The name of the tax.
applied_discount
"applied_discount": {
  "title": "Title of the discount",
  "description": "Description",
  "value": "10",
  "value_type": "fixed_amount",
  "amount": "10"
}

The discount applied to the line item or the draft order object. Each draft order object can have one applied_discount object and each draft order line item can have its own applied_discount. The object has the following properties:

  • title: Title of the discount.
  • description: Reason for the discount.
  • value: The value of the discount. If the type of discount is fixed_amount, then it corresponds to a fixed dollar amount. If the type is percentage, then it corresponds to percentage.
  • value_type: The type of discount. Valid values: percentage, fixed_amount.
  • amount: The applied amount of the discount, based on the setting of value_type. For more information, see Applying discounts.
taxes_included
"taxes_included": false

Whether taxes are included in the order subtotal. Valid values are true or false.

total_tax
"total_tax": "11.94"

The sum of all the taxes applied to the order.

subtotal_price
"subtotal_price": 398.0

the price of the order before shipping and taxes.

total_price
"total_price": "409.94"

The sum of all the prices of all the items in the order, taxes and discounts included.

completed_at
"completed_at": "2012-08-24T14:02:15-04:00"

The date and time (ISO 8601 format) when the order is created and the draft order is completed.

created_at
"created_at": "2008-01-10T11:00:00-05:00"

The date and time (ISO 8601 format) when the order was created in Shopify.

updated_at
"updated_at": "2012-08-24T14:02:15-04:00"

The date and time (ISO 8601 format) when the order was last modified.

status
"status": "authorized"

The status of a draft order as it transitions into an order. When a draft order is created it is set to open status. The invoice can then be sent to the customer, and status changes to invoice_sent. The draft order can then be paid, set to pending, or paid by credit card. In each case, the draft order is set to completed and an order is created.

After a draft order is set to completed the only further modifications that can be made are adding tags or metafields.

Valid values:

  • open: Draft order is open.
  • invoice_sent: Invoice has been sent for the draft order.
  • completed: Draft order has been completed and turned into an order.

Endpoints

POST /admin/api/2019-04/draft_orders.json

Creates a draft order.

Using the DraftOrder resource you can create orders in draft state using product variant line items, or custom line items. To create a product variant draft order, provide the variant_id, quantity and discount properties. To create a custom line item, provide the title, price, taxable, and quantity properties.


About custom shipping lines

You can use the DraftOrder resource to send orders with custom shipping lines. A custom shipping line includes a title and price with handle set to Nil. A shipping line with a carrier provided shipping rate (currently set via the Shopify admin) includes the shipping rate handle.

Applying discounts

A draft order and its line items can have one discount each. Calculations for discounts are based on the setting of the value_type property, which can be set to either fixed_amount or percentage. For example, you can apply a fixed amount discount to a draft order to reduce the price by the specified value property. When you use a percentage discount, the discount amount property is the price multiplied by the value property. For line item discounts, the value property is applied per individual unit of the item, based on the line item's quantity.


Calculating line item discount amounts

For fixed_amount discounts, the total amount corresponds to the line item quantity times the value of the discount. For percentage discounts, the total amount corresponds to the following:


amount = floor(price * quantity * value) / 100, where floor() is the usual round down function.


For non-fractional currencies, this formula needs to use round() instead of floor(), and the division by 100 takes place inside the rounding, resulting in a non-fractional value. Otherwise, an error is returned.


amount = round(price * quantity * value / 100)


Line item examples

Fixed amount discount

For a $19.99 line item with quantity of 2 and with $5 dollars off, discount amount corresponds to $10 ($5 * 2):


applied_discount: { "value_type": "fixed_amount", "value": 5, "amount": 10 }


For a fixed amount example, see Create a draft order with a discount.


Percentage discount

For a $19.99 line item with quantity of 2 and with 15% off, discount amount corresponds to $5.99 (floor ($19.99 * 2 * 15) / 100):


applied_discount: { "value_type": "percentage", "value": 15, "amount": 5.99 }


For a percentage example, see Set a percent discount on a line item.

Loading and removing customers

You can load a customer to a draft order by sending the customer_id as part of the draft order object. The recommended way to remove a customer from a draft order is to make a POST request with the Customer object set to null, without specifying an email, shipping address, or billing address. A customer may also be removed by setting customer, email, shipping_address, and billing_address to null.

use_customer_default_address

An optional boolean that you can send as part of a draft order object to load customer shipping information. Valid values: true or false.

customer_id

Used to load the customer. When a customer is loaded, the customer’s email address is also associated.

Create a simple draft order with only a product variant ID.

POST /admin/api/2019-04/draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "variant_id": 447654529,
        "quantity": 1
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order": {
    "id": 1069920480,
    "note": null,
    "email": null,
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:57:23-04:00",
    "updated_at": "2019-04-09T10:57:23-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D5",
    "status": "open",
    "line_items": [
      {
        "variant_id": 447654529,
        "product_id": 921728736,
        "title": "IPod Touch 8GB",
        "variant_title": "Black",
        "sku": "IPOD2009BLACK",
        "vendor": "Apple",
        "quantity": 1,
        "requires_shipping": true,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "shipwire-app",
        "grams": 567,
        "tax_lines": [
          {
            "rate": 0.05,
            "title": "GST",
            "price": "9.95"
          },
          {
            "rate": 0.08,
            "title": "Tax",
            "price": "15.92"
          }
        ],
        "applied_discount": null,
        "name": "IPod Touch 8GB - Black",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118545"
      }
    ],
    "shipping_address": null,
    "billing_address": null,
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/c4432d6494c612f71f9d2ee7103b68d7",
    "applied_discount": null,
    "order_id": null,
    "shipping_line": null,
    "tax_lines": [
      {
        "rate": 0.05,
        "title": "GST",
        "price": "9.95"
      },
      {
        "rate": 0.08,
        "title": "Tax",
        "price": "15.92"
      }
    ],
    "tags": "",
    "note_attributes": [],
    "total_price": "224.87",
    "subtotal_price": "199.00",
    "total_tax": "25.87",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/1069920480",
    "customer": null
  }
}

Create a draft order with a discount

POST /admin/api/2019-04/draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "title": "Custom Tee",
        "price": "20.00",
        "quantity": 2
      }
    ],
    "applied_discount": {
      "description": "Custom discount",
      "value_type": "fixed_amount",
      "value": "10.0",
      "amount": "10.00",
      "title": "Custom"
    },
    "customer": {
      "id": 207119551
    },
    "use_customer_default_address": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order": {
    "id": 1069920481,
    "note": null,
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:57:24-04:00",
    "updated_at": "2019-04-09T10:57:24-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D5",
    "status": "open",
    "line_items": [
      {
        "variant_id": null,
        "product_id": null,
        "title": "Custom Tee",
        "variant_title": null,
        "sku": null,
        "vendor": null,
        "quantity": 2,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 0,
        "tax_lines": [],
        "applied_discount": null,
        "name": "Custom Tee",
        "properties": [],
        "custom": true,
        "price": "20.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118546"
      }
    ],
    "shipping_address": {
      "first_name": null,
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": null,
      "address2": "",
      "company": null,
      "latitude": null,
      "longitude": null,
      "name": "",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": null,
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": null,
      "address2": "",
      "company": null,
      "latitude": null,
      "longitude": null,
      "name": "",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/6641ceb348d517a628e2290d511b1c9b",
    "applied_discount": {
      "description": "Custom discount",
      "value": "10.0",
      "title": "Custom",
      "amount": "10.00",
      "value_type": "fixed_amount"
    },
    "order_id": null,
    "shipping_line": null,
    "tax_lines": [],
    "tags": "",
    "note_attributes": [],
    "total_price": "30.00",
    "subtotal_price": "30.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/1069920481",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  }
}

Create a draft order with a discounted line item

POST /admin/api/2019-04/draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "title": "Custom Tee",
        "price": "20.00",
        "quantity": 1,
        "applied_discount": {
          "description": "Custom discount",
          "value_type": "fixed_amount",
          "value": "10.0",
          "amount": "10.0",
          "title": "Custom"
        }
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order": {
    "id": 1069920482,
    "note": null,
    "email": null,
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:57:25-04:00",
    "updated_at": "2019-04-09T10:57:25-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D5",
    "status": "open",
    "line_items": [
      {
        "variant_id": null,
        "product_id": null,
        "title": "Custom Tee",
        "variant_title": null,
        "sku": null,
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 0,
        "tax_lines": [
          {
            "rate": 0.05,
            "title": "GST",
            "price": "0.50"
          },
          {
            "rate": 0.08,
            "title": "Tax",
            "price": "0.80"
          }
        ],
        "applied_discount": {
          "description": "Custom discount",
          "value": "10.0",
          "title": "Custom",
          "amount": "10.00",
          "value_type": "fixed_amount"
        },
        "name": "Custom Tee",
        "properties": [],
        "custom": true,
        "price": "20.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118547"
      }
    ],
    "shipping_address": null,
    "billing_address": null,
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/643cacd2ff18439e1d2b4d94a9a52501",
    "applied_discount": null,
    "order_id": null,
    "shipping_line": null,
    "tax_lines": [
      {
        "rate": 0.05,
        "title": "GST",
        "price": "0.50"
      },
      {
        "rate": 0.08,
        "title": "Tax",
        "price": "0.80"
      }
    ],
    "tags": "",
    "note_attributes": [],
    "total_price": "11.30",
    "subtotal_price": "10.00",
    "total_tax": "1.30",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/1069920482",
    "customer": null
  }
}

Create a draft order with a percent discount on a line item

POST /admin/api/2019-04/draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "title": "Custom Tee",
        "price": "20.00",
        "quantity": 1,
        "applied_discount": {
          "description": "Custom discount",
          "value_type": "percentage",
          "value": "10.0",
          "amount": "2.0",
          "title": "Custom"
        }
      }
    ]
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order": {
    "id": 1069920483,
    "note": null,
    "email": null,
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:57:25-04:00",
    "updated_at": "2019-04-09T10:57:25-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D5",
    "status": "open",
    "line_items": [
      {
        "variant_id": null,
        "product_id": null,
        "title": "Custom Tee",
        "variant_title": null,
        "sku": null,
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 0,
        "tax_lines": [
          {
            "rate": 0.05,
            "title": "GST",
            "price": "0.90"
          },
          {
            "rate": 0.08,
            "title": "Tax",
            "price": "1.44"
          }
        ],
        "applied_discount": {
          "description": "Custom discount",
          "value": "10.0",
          "title": "Custom",
          "amount": "2.00",
          "value_type": "percentage"
        },
        "name": "Custom Tee",
        "properties": [],
        "custom": true,
        "price": "20.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118548"
      }
    ],
    "shipping_address": null,
    "billing_address": null,
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/1374615138a9e3319a984635ec4d2d4a",
    "applied_discount": null,
    "order_id": null,
    "shipping_line": null,
    "tax_lines": [
      {
        "rate": 0.05,
        "title": "GST",
        "price": "0.90"
      },
      {
        "rate": 0.08,
        "title": "Tax",
        "price": "1.44"
      }
    ],
    "tags": "",
    "note_attributes": [],
    "total_price": "20.34",
    "subtotal_price": "18.00",
    "total_tax": "2.34",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/1069920483",
    "customer": null
  }
}

Create custom draft order

POST /admin/api/2019-04/draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "title": "Custom Tee",
        "price": "20.00",
        "quantity": 2
      }
    ],
    "customer": {
      "id": 207119551
    },
    "use_customer_default_address": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order": {
    "id": 1069920484,
    "note": null,
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:57:26-04:00",
    "updated_at": "2019-04-09T10:57:26-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D5",
    "status": "open",
    "line_items": [
      {
        "variant_id": null,
        "product_id": null,
        "title": "Custom Tee",
        "variant_title": null,
        "sku": null,
        "vendor": null,
        "quantity": 2,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 0,
        "tax_lines": [],
        "applied_discount": null,
        "name": "Custom Tee",
        "properties": [],
        "custom": true,
        "price": "20.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118549"
      }
    ],
    "shipping_address": {
      "first_name": null,
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": null,
      "address2": "",
      "company": null,
      "latitude": null,
      "longitude": null,
      "name": "",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": null,
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": null,
      "address2": "",
      "company": null,
      "latitude": null,
      "longitude": null,
      "name": "",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/52d89a4ae8dd672b09f44560cfcf9a62",
    "applied_discount": null,
    "order_id": null,
    "shipping_line": null,
    "tax_lines": [],
    "tags": "",
    "note_attributes": [],
    "total_price": "40.00",
    "subtotal_price": "40.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/1069920484",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  }
}
PUT /admin/api/2019-04/draft_orders/994118539.json
Updates a draft order

Add a note to a draft order

PUT /admin/api/2019-04/draft_orders/#{draft_order_id}.json
{
  "draft_order": {
    "id": 994118539,
    "note": "Customer contacted us about a custom engraving on this iPod"
  }
}
View Response
HTTP/1.1 202 Accepted
{
  "draft_order": {
    "id": 994118539,
    "note": "Customer contacted us about a custom engraving on this iPod",
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:02:43-04:00",
    "updated_at": "2019-04-09T10:57:27-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D2",
    "status": "open",
    "line_items": [
      {
        "variant_id": 39072856,
        "product_id": 632910392,
        "title": "IPod Nano - 8gb",
        "variant_title": "green",
        "sku": "IPOD2008GREEN",
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 567,
        "tax_lines": [],
        "applied_discount": null,
        "name": "IPod Nano - 8gb - green",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
      }
    ],
    "shipping_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
    "applied_discount": {
      "description": "$5promo",
      "value": "5.0",
      "title": null,
      "amount": "5.00",
      "value_type": "fixed_amount"
    },
    "order_id": null,
    "shipping_line": {
      "title": "UPS Ground",
      "custom": false,
      "handle": "ups-3-12.25",
      "price": "12.25"
    },
    "tax_lines": [],
    "tags": "Wholesale",
    "note_attributes": [],
    "total_price": "206.25",
    "subtotal_price": "194.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  }
}

Set a discount on a draft order

PUT /admin/api/2019-04/draft_orders/#{draft_order_id}.json
{
  "draft_order": {
    "id": 994118539,
    "applied_discount": {
      "description": "Custom discount",
      "value_type": "percentage",
      "value": "10.0",
      "amount": "19.90",
      "title": "Custom"
    }
  }
}
View Response
HTTP/1.1 202 Accepted
{
  "draft_order": {
    "id": 994118539,
    "note": "rush order",
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:02:43-04:00",
    "updated_at": "2019-04-09T10:57:28-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D2",
    "status": "open",
    "line_items": [
      {
        "variant_id": 39072856,
        "product_id": 632910392,
        "title": "IPod Nano - 8gb",
        "variant_title": "green",
        "sku": "IPOD2008GREEN",
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 567,
        "tax_lines": [],
        "applied_discount": null,
        "name": "IPod Nano - 8gb - green",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
      }
    ],
    "shipping_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
    "applied_discount": {
      "description": "Custom discount",
      "value": "10.0",
      "title": "Custom",
      "amount": "19.90",
      "value_type": "percentage"
    },
    "order_id": null,
    "shipping_line": {
      "title": "UPS Ground",
      "custom": false,
      "handle": "ups-3-12.25",
      "price": "12.25"
    },
    "tax_lines": [],
    "tags": "Wholesale",
    "note_attributes": [],
    "total_price": "191.35",
    "subtotal_price": "179.10",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  }
}
GET /admin/api/2019-04/draft_orders.json
Retrieves a list of draft orders
fields

A comma-separated list of fields to include in the response

limit

Amount of results

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID

updated_at_min

Show orders last updated after date (format: 2014-04-25T16:15:47-04:00)

updated_at_max

Show orders last updated before date (format: 2014-04-25T16:15:47-04:00)

ids

Filter by list of IDs

status
  • open: All open orders (default)
  • invoice_sent: Show only closed orders
  • completed: Show only cancelled orders
fields

comma-separated list of fields to include in the response

List all draft orders

GET /admin/api/2019-04/draft_orders.json
View Response
HTTP/1.1 200 OK
{
  "draft_orders": [
    {
      "id": 72885271,
      "note": "rush order",
      "email": "bob.norman@hostmail.com",
      "taxes_included": true,
      "currency": "USD",
      "invoice_sent_at": null,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "tax_exempt": false,
      "completed_at": null,
      "name": "#D4",
      "status": "completed",
      "line_items": [
        {
          "variant_id": 39072856,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "green",
          "sku": "IPOD2008GREEN",
          "vendor": null,
          "quantity": 2,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - green",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/498266019"
        }
      ],
      "shipping_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "billing_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "invoice_url": "https://apple.myshopify.com/690933842/invoices/f945c7e2b158dbb69fa642cb8d79171f",
      "applied_discount": null,
      "order_id": 450789469,
      "shipping_line": null,
      "tax_lines": [],
      "tags": "",
      "note_attributes": [],
      "total_price": "409.94",
      "subtotal_price": "398.00",
      "total_tax": "11.94",
      "admin_graphql_api_id": "gid://shopify/DraftOrder/72885271",
      "customer": {
        "id": 207119551,
        "email": "bob.norman@hostmail.com",
        "accepts_marketing": false,
        "created_at": "2019-04-09T10:02:43-04:00",
        "updated_at": "2019-04-09T10:02:43-04:00",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": 1,
        "state": "disabled",
        "total_spent": "199.65",
        "last_order_id": 450789469,
        "note": null,
        "verified_email": true,
        "multipass_identifier": null,
        "tax_exempt": false,
        "phone": null,
        "tags": "",
        "last_order_name": "#1001",
        "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
        "marketing_opt_in_level": null,
        "admin_graphql_api_id": "gid://shopify/Customer/207119551",
        "default_address": {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      }
    },
    {
      "id": 622762746,
      "note": "rush order",
      "email": "bob.norman@hostmail.com",
      "taxes_included": false,
      "currency": "USD",
      "invoice_sent_at": null,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "tax_exempt": false,
      "completed_at": null,
      "name": "#D1",
      "status": "open",
      "line_items": [
        {
          "variant_id": 39072856,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "green",
          "sku": "IPOD2008GREEN",
          "vendor": null,
          "quantity": 1,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - green",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/466157049"
        },
        {
          "variant_id": null,
          "product_id": null,
          "title": "IPod Nano Engraving",
          "variant_title": null,
          "sku": "IPODENGRAVING",
          "vendor": null,
          "quantity": 1,
          "requires_shipping": false,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 0,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano Engraving",
          "properties": [],
          "custom": true,
          "price": "30.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/605833968"
        },
        {
          "variant_id": 457924702,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "black",
          "sku": "IPOD2008BLACK",
          "vendor": null,
          "quantity": 3,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - black",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/783764327"
        }
      ],
      "shipping_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "billing_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "invoice_url": "https://apple.myshopify.com/690933842/invoices/f1df1a91d10a6d7704cf2f0315461api",
      "applied_discount": null,
      "order_id": null,
      "shipping_line": {
        "title": "custom shipping",
        "custom": true,
        "handle": null,
        "price": "10.00"
      },
      "tax_lines": [],
      "tags": "",
      "note_attributes": [],
      "total_price": "836.00",
      "subtotal_price": "826.00",
      "total_tax": "0.00",
      "admin_graphql_api_id": "gid://shopify/DraftOrder/622762746",
      "customer": {
        "id": 207119551,
        "email": "bob.norman@hostmail.com",
        "accepts_marketing": false,
        "created_at": "2019-04-09T10:02:43-04:00",
        "updated_at": "2019-04-09T10:02:43-04:00",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": 1,
        "state": "disabled",
        "total_spent": "199.65",
        "last_order_id": 450789469,
        "note": null,
        "verified_email": true,
        "multipass_identifier": null,
        "tax_exempt": false,
        "phone": null,
        "tags": "",
        "last_order_name": "#1001",
        "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
        "marketing_opt_in_level": null,
        "admin_graphql_api_id": "gid://shopify/Customer/207119551",
        "default_address": {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      }
    },
    {
      "id": 691042898,
      "note": "rush order",
      "email": "bob.norman@hostmail.com",
      "taxes_included": true,
      "currency": "USD",
      "invoice_sent_at": "2016-12-31T19:00:00-05:00",
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "tax_exempt": false,
      "completed_at": "2016-12-31T19:00:00-05:00",
      "name": "#D4",
      "status": "completed",
      "line_items": [
        {
          "variant_id": 39072856,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "green",
          "sku": "IPOD2008GREEN",
          "vendor": null,
          "quantity": 1,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - green",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/158115779"
        }
      ],
      "shipping_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "billing_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "invoice_url": "https://apple.myshopify.com/690933842/invoices/56dd92fb7adc1a2c38402b1aab15b2f4",
      "applied_discount": null,
      "order_id": 450789469,
      "shipping_line": {
        "title": "UPS Ground",
        "custom": false,
        "handle": "ups-3-12.25",
        "price": "12.25"
      },
      "tax_lines": [],
      "tags": "",
      "note_attributes": [],
      "total_price": "409.94",
      "subtotal_price": "398.00",
      "total_tax": "11.94",
      "admin_graphql_api_id": "gid://shopify/DraftOrder/691042898",
      "customer": {
        "id": 207119551,
        "email": "bob.norman@hostmail.com",
        "accepts_marketing": false,
        "created_at": "2019-04-09T10:02:43-04:00",
        "updated_at": "2019-04-09T10:02:43-04:00",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": 1,
        "state": "disabled",
        "total_spent": "199.65",
        "last_order_id": 450789469,
        "note": null,
        "verified_email": true,
        "multipass_identifier": null,
        "tax_exempt": false,
        "phone": null,
        "tags": "",
        "last_order_name": "#1001",
        "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
        "marketing_opt_in_level": null,
        "admin_graphql_api_id": "gid://shopify/Customer/207119551",
        "default_address": {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      }
    },
    {
      "id": 994118539,
      "note": "rush order",
      "email": "bob.norman@hostmail.com",
      "taxes_included": false,
      "currency": "USD",
      "invoice_sent_at": null,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "tax_exempt": false,
      "completed_at": null,
      "name": "#D2",
      "status": "open",
      "line_items": [
        {
          "variant_id": 39072856,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "green",
          "sku": "IPOD2008GREEN",
          "vendor": null,
          "quantity": 1,
          "requires_shipping": false,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - green",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
        }
      ],
      "shipping_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "billing_address": {
        "first_name": "Bob",
        "address1": "Chestnut Street 92",
        "phone": "555-625-1199",
        "city": "Louisville",
        "zip": "40202",
        "province": "Kentucky",
        "country": "United States",
        "last_name": "Norman",
        "address2": "",
        "company": null,
        "latitude": 45.41634,
        "longitude": -75.6868,
        "name": "Bob Norman",
        "country_code": "US",
        "province_code": "KY"
      },
      "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
      "applied_discount": {
        "description": "$5promo",
        "value": "5.0",
        "title": null,
        "amount": "5.00",
        "value_type": "fixed_amount"
      },
      "order_id": null,
      "shipping_line": {
        "title": "UPS Ground",
        "custom": false,
        "handle": "ups-3-12.25",
        "price": "12.25"
      },
      "tax_lines": [],
      "tags": "Wholesale",
      "note_attributes": [],
      "total_price": "206.25",
      "subtotal_price": "194.00",
      "total_tax": "0.00",
      "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
      "customer": {
        "id": 207119551,
        "email": "bob.norman@hostmail.com",
        "accepts_marketing": false,
        "created_at": "2019-04-09T10:02:43-04:00",
        "updated_at": "2019-04-09T10:02:43-04:00",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": 1,
        "state": "disabled",
        "total_spent": "199.65",
        "last_order_id": 450789469,
        "note": null,
        "verified_email": true,
        "multipass_identifier": null,
        "tax_exempt": false,
        "phone": null,
        "tags": "",
        "last_order_name": "#1001",
        "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
        "marketing_opt_in_level": null,
        "admin_graphql_api_id": "gid://shopify/Customer/207119551",
        "default_address": {
          "id": 207119551,
          "customer_id": 207119551,
          "first_name": null,
          "last_name": null,
          "company": null,
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "province": "Kentucky",
          "country": "United States",
          "zip": "40202",
          "phone": "555-625-1199",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      }
    },
    {
      "id": 1012750869,
      "note": "rush order",
      "email": "bob.norman@hostmail.com",
      "taxes_included": false,
      "currency": "USD",
      "invoice_sent_at": null,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "tax_exempt": false,
      "completed_at": null,
      "name": "#D2",
      "status": "open",
      "line_items": [
        {
          "variant_id": 39072856,
          "product_id": 632910392,
          "title": "IPod Nano - 8gb",
          "variant_title": "green",
          "sku": "IPOD2008GREEN",
          "vendor": null,
          "quantity": 1,
          "requires_shipping": true,
          "taxable": true,
          "gift_card": false,
          "fulfillment_service": "manual",
          "grams": 567,
          "tax_lines": [],
          "applied_discount": null,
          "name": "IPod Nano - 8gb - green",
          "properties": [],
          "custom": false,
          "price": "199.00",
          "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/294997122"
        }
      ],
      "shipping_address": null,
      "billing_address": null,
      "invoice_url": "https://apple.myshopify.com/690933842/invoices/f1df1a91d10a6d7704cf2f0315461noaddressapi",
      "applied_discount": null,
      "order_id": null,
      "shipping_line": null,
      "tax_lines": [],
      "tags": "",
      "note_attributes": [],
      "total_price": "836.00",
      "subtotal_price": "826.00",
      "total_tax": "0.00",
      "admin_graphql_api_id": "gid://shopify/DraftOrder/1012750869",
      "customer": null
    }
  ]
}
GET /admin/api/2019-04/draft_orders/994118539.json
Retrieves a specific draft order
fields

A comma-separated list of fields to include in the response

Get a representation of a single draft order

GET /admin/api/2019-04/draft_orders/#{draft_order_id}.json
View Response
HTTP/1.1 200 OK
{
  "draft_order": {
    "id": 994118539,
    "note": "rush order",
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:02:43-04:00",
    "updated_at": "2019-04-09T10:02:43-04:00",
    "tax_exempt": false,
    "completed_at": null,
    "name": "#D2",
    "status": "open",
    "line_items": [
      {
        "variant_id": 39072856,
        "product_id": 632910392,
        "title": "IPod Nano - 8gb",
        "variant_title": "green",
        "sku": "IPOD2008GREEN",
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 567,
        "tax_lines": [],
        "applied_discount": null,
        "name": "IPod Nano - 8gb - green",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
      }
    ],
    "shipping_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
    "applied_discount": {
      "description": "$5promo",
      "value": "5.0",
      "title": null,
      "amount": "5.00",
      "value_type": "fixed_amount"
    },
    "order_id": null,
    "shipping_line": {
      "title": "UPS Ground",
      "custom": false,
      "handle": "ups-3-12.25",
      "price": "12.25"
    },
    "tax_lines": [],
    "tags": "Wholesale",
    "note_attributes": [],
    "total_price": "206.25",
    "subtotal_price": "194.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      }
    }
  }
}
GET /admin/api/2019-04/draft_orders/count.json
Retrieves a count of all the draft orders
fields

A comma-separated list of fields to include in the response

limit

Amount of results

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID

ids

Filter by list of IDs

status
  • open: All open orders (default)
  • invoice_sent: Show only closed orders
  • completed: Show only cancelled orders

Count all draft orders

GET /admin/api/2019-04/draft_orders/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 5
}
POST /admin/api/2019-04/draft_orders/994118539/send_invoice.json
Sends an invoice for the draft order

Send a customized invoice

POST /admin/api/2019-04/draft_orders/#{draft_order_id}/send_invoice.json
{
  "draft_order_invoice": {
    "to": "first@example.com",
    "from": "steve@apple.com",
    "bcc": [
      "steve@apple.com"
    ],
    "subject": "Apple Computer Invoice",
    "custom_message": "Thank you for ordering!"
  }
}
View Response
HTTP/1.1 201 Created
{
  "draft_order_invoice": {
    "to": "first@example.com",
    "from": "steve@apple.com",
    "subject": "Apple Computer Invoice",
    "custom_message": "Thank you for ordering!",
    "bcc": [
      "steve@apple.com"
    ]
  }
}

Send the default invoice

POST /admin/api/2019-04/draft_orders/#{draft_order_id}/send_invoice.json
{
  "draft_order_invoice": {}
}
View Response
HTTP/1.1 201 Created
{
  "draft_order_invoice": {
    "to": "bob.norman@hostmail.com",
    "from": "steve@apple.com",
    "subject": "Draft Order #D2",
    "custom_message": "",
    "bcc": []
  }
}
DELETE /admin/api/2019-04/draft_orders/994118539.json
Deletes a draft order

Permanently delete a draft order

DELETE /admin/api/2019-04/draft_orders/#{draft_order_id}.json
View Response
HTTP/1.1 200 OK
{
}
PUT /admin/api/2019-04/draft_orders/994118539/complete.json
Completes a draft order.

Using the DraftOrder resource, you can create a draft order and transition it to an order.


The following flows are supported:


  • Create a draft order that calculates taxes and totals but accept payment from the customer outside of Shopify.
  • Create a draft order and send an invoice to the customer.
  • Use the DraftOrder and Checkout resources to create a checkout from a draft order (sales channel apps only).
payment_pending
  • true: Sets payment pending to true.
  • false: Sets payment pending to false. default value.

Complete a draft order, marking it as paid

PUT /admin/api/2019-04/draft_orders/#{draft_order_id}/complete.json
View Response
HTTP/1.1 200 OK
{
  "draft_order": {
    "id": 994118539,
    "note": "rush order",
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:02:43-04:00",
    "updated_at": "2019-04-09T10:57:20-04:00",
    "tax_exempt": false,
    "completed_at": "2019-04-09T10:57:20-04:00",
    "name": "#D2",
    "status": "completed",
    "line_items": [
      {
        "variant_id": 39072856,
        "product_id": 632910392,
        "title": "IPod Nano - 8gb",
        "variant_title": "green",
        "sku": "IPOD2008GREEN",
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 567,
        "tax_lines": [],
        "applied_discount": null,
        "name": "IPod Nano - 8gb - green",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
      }
    ],
    "shipping_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
    "applied_discount": {
      "description": "$5promo",
      "value": "5.0",
      "title": null,
      "amount": "5.00",
      "value_type": "fixed_amount"
    },
    "order_id": 1073459986,
    "shipping_line": {
      "title": "UPS Ground",
      "custom": false,
      "handle": "ups-3-12.25",
      "price": "12.25"
    },
    "tax_lines": [],
    "tags": "Wholesale",
    "note_attributes": [],
    "total_price": "206.25",
    "subtotal_price": "194.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": false
      }
    }
  }
}

Complete a draft order, marking it as pending

PUT /admin/api/2019-04/draft_orders/#{draft_order_id}/complete.json?payment_pending=true
View Response
HTTP/1.1 200 OK
{
  "draft_order": {
    "id": 994118539,
    "note": "rush order",
    "email": "bob.norman@hostmail.com",
    "taxes_included": false,
    "currency": "USD",
    "invoice_sent_at": null,
    "created_at": "2019-04-09T10:02:43-04:00",
    "updated_at": "2019-04-09T10:57:22-04:00",
    "tax_exempt": false,
    "completed_at": "2019-04-09T10:57:22-04:00",
    "name": "#D2",
    "status": "completed",
    "line_items": [
      {
        "variant_id": 39072856,
        "product_id": 632910392,
        "title": "IPod Nano - 8gb",
        "variant_title": "green",
        "sku": "IPOD2008GREEN",
        "vendor": null,
        "quantity": 1,
        "requires_shipping": false,
        "taxable": true,
        "gift_card": false,
        "fulfillment_service": "manual",
        "grams": 567,
        "tax_lines": [],
        "applied_discount": null,
        "name": "IPod Nano - 8gb - green",
        "properties": [],
        "custom": false,
        "price": "199.00",
        "admin_graphql_api_id": "gid://shopify/DraftOrderLineItem/994118539"
      }
    ],
    "shipping_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "billing_address": {
      "first_name": "Bob",
      "address1": "Chestnut Street 92",
      "phone": "555-625-1199",
      "city": "Louisville",
      "zip": "40202",
      "province": "Kentucky",
      "country": "United States",
      "last_name": "Norman",
      "address2": "",
      "company": null,
      "latitude": 45.41634,
      "longitude": -75.6868,
      "name": "Bob Norman",
      "country_code": "US",
      "province_code": "KY"
    },
    "invoice_url": "https://apple.myshopify.com/690933842/invoices/ba8dcf6c022ccad3d47e3909e378e33f",
    "applied_discount": {
      "description": "$5promo",
      "value": "5.0",
      "title": null,
      "amount": "5.00",
      "value_type": "fixed_amount"
    },
    "order_id": 1073459987,
    "shipping_line": {
      "title": "UPS Ground",
      "custom": false,
      "handle": "ups-3-12.25",
      "price": "12.25"
    },
    "tax_lines": [],
    "tags": "Wholesale",
    "note_attributes": [],
    "total_price": "206.25",
    "subtotal_price": "194.00",
    "total_tax": "0.00",
    "admin_graphql_api_id": "gid://shopify/DraftOrder/994118539",
    "customer": {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2019-04-09T10:02:43-04:00",
      "updated_at": "2019-04-09T10:02:43-04:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": null,
      "tags": "",
      "last_order_name": "#1001",
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "admin_graphql_api_id": "gid://shopify/Customer/207119551",
      "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": false
      }
    }
  }
}

Sign up for a Partner account to get started.

Sign up