POST /admin/api/{api_version}/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.

Note

If you are using this endpoint with a Partner development store or a trial store, then you can only create five draft orders per minute.

Polling

When you create and update draft orders some calculations are done asynchronously, such as calculating shipping and taxes. There might be times when a draft order is created but these calculations haven't completed. In these cases, you need to poll the draft order until the calculations are finished.
When a draft order requires polling, a 202 accepted response code is returned along with location and retry-after response headers. The location header refers to the URL to be polled, and retry-after denotes the interval (in seconds) at which polling requests should be sent. When the draft order is ready, a 200 OK response code will be returned.

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 Create 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.

Servers

• https://{store_name}.myshopify.com
• {store_name}.myshopify.com

Path parameters

Name	Type	Required	Description
api_version	String	Yes

Request headers

Name	Type	Required	Description
Content-Type	String	Yes	The media type of the request body. Default value: "application/json"
x-shopify-access-token	String	No

Request body fields

Name	Type	Required	Description
draft_order	Object	No
draft_order.line_items[]	Array	No
draft_order.line_items[].price	String	No
draft_order.line_items[].quantity	Number	No
draft_order.line_items[].title	String	No
draft_order.line_items[].applied_discount	Object	No
draft_order.line_items[].applied_discount.description	String	No
draft_order.line_items[].applied_discount.amount	String	No
draft_order.line_items[].applied_discount.value_type	String	No
draft_order.line_items[].applied_discount.title	String	No
draft_order.line_items[].applied_discount.value	String	No

How to start integrating

1. Add HTTP Task to your workflow definition.
2. Search for the API you want to integrate with and click on the name.
   • This loads the API reference documentation and prepares the Http request settings.
3. Click Test request to test run your request to the API and see the API's response.