DraftOrder

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.

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 }

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 }

Loading and removing customers

You can load a customer to a draft order by sending the customer_id as part of the draft order resource. We recommend removing a customer from a draft order by making a POST request with the Customer resource set to null, without specifying an email, shipping address, or billing address. A customer can also be removed by setting customer, email, shipping_address, and billing_address to null.

Sends an invoice for the draft order.

You can include the following parameters in the body of the request:

• draft_order_invoice: The resource to send in the body of the request.
  • to: The email address that will populate the to field of the email.
  • from: The email address that will populate the from field of the email.
  • bcc: The list of email addresses to include in the bcc field of the email. Emails must be associated with staff accounts on the shop.
  • subject: The email subject.
  • custom_message: The custom message displayed in the email.

Retrieves a list of draft orders. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Retrieves a specific draft order

Retrieves a count of draft orders

Updates a draft order.

All non read-only properties of the DraftOrder Resource can be edited.

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.

Deletes a draft order