Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

DraftOrder

Requires draft_orders access scope.
Requires access to protected customer data.

Merchants can use draft orders to create orders on behalf of their customers. Draft orders are useful for merchants that need to do the following tasks:

  • Create new orders for sales made by phone, in person, by chat, or elsewhere. When a merchant accepts payment for a draft order, an order is created.
  • 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 orders manually from active sales channels.
  • Sell products at discount or wholesale rates.
  • Take pre-orders.
Note

The Draft Order resource doesn't expose reserve inventory information.

Caution: Only use this data if it is necessary for the intended app functionality. Shopify retains the ability to restrict access to API Access scopes for apps not requiring legitimate use of the associated data.

Was this section helpful?
#

Endpoints

Anchor to

The DraftOrder resource

Anchor to

Properties

id
read-only
->
id

The ID of the draft order.

order_id
read-only
->
id

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

name
read-only
->
name

Name of the draft order.

customer
->
customer

The customer resource, which contains information about the customer. Learn more about loading and removing customers. For more information about the customer resource, see the Customer documentation.

shipping_address
->
shippingAddress

The address to ship the order to. The shipping_address is optional and will not be available on orders that don't require shipping. The shipping_address resource has the following properties:

Show shipping_address 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 alphanumeric abbreviation of the state or province of the shipping address.
  • zip: The zip or postal code of the shipping address.
billing_address
->
billingAddress

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. The billing_address resource has the following properties:

Show billing_address 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 alphanumeric abbreviation of the region for the billing address.
  • zip: The postal code of the billing address, such as zip, postcode, or Eircode.
note
->
note2

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

note_attributes
->
customAttributes

The extra information that's added to the order. The information appears in theAdditional details section of an order details page. Each array entry must contain a hash with name and value keys.

email
->
email

The customer's email address.

currency
read-only
->
currencyCode

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

invoice_sent_at
read-only
->
invoiceSentAt

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

invoice_url
read-only
->
invoiceUrl

The URL for the invoice.

Was this section helpful?
{}

The DraftOrder resource

{
"id": 450789469,
"order_id": {
"id": 456789101
},
"name": "#1001",
"customer": {
"id": 207119551,
"email": "bob.norman@mail.example.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,
"tax_exemptions": {},
"phone": "+13125551212",
"tags": "loyal",
"last_order_name": "#1001",
"currency": "USD",
"addresses": {},
"admin_graphql_api_id": "gid://shopify/Customer/207119551",
"default_address": {}
},
"shipping_address": {
"address1": "123 Amoebobacterieae St",
"address2": "",
"city": "Ottawa",
"company": null,

Anchor to POST request, Create a new DraftOrder
post
Create a new DraftOrder

draftOrderCreate

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 }

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.

Anchor to Parameters of Create a new DraftOrderParameters

api_version
string
required
customer_id

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

use_customer_default_address
boolean
default false

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

Was this section helpful?

Anchor to post-draft-orders-examplesExamples

Create a draft order with a discount

Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.line_items:[{"title":"Custom Tee","price":"20.00","quantity":2}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
draft_order.applied_discount:{"description":"Custom discount","value_type":"fixed_amount","value":"10.0","amount":"10.00","title":"Custom"}
->
appliedDiscount

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

Show applied_discount 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.
draft_order.customer:{"id":207119551}

The customer resource, which contains information about the customer. Learn more about loading and removing customers. For more information about the customer resource, see the Customer documentation.

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

Request body
draft_order
Draft_order resource
Show draft_order properties
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"}}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.

Create custom draft order

Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.line_items:[{"title":"Custom Tee","price":"20.00","quantity":2}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
draft_order.customer:{"id":207119551}

The customer resource, which contains information about the customer. Learn more about loading and removing customers. For more information about the customer resource, see the Customer documentation.

Create draft order with custom billing address

Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.line_items:[{"variant_id":447654529,"quantity":1}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
draft_order.billing_address:{"first_name":"Bob","last_name":"Norman","address1":"123 Main St","city":"Anytown","province":"ON","country":"Canada","zip":"A1B2C3","phone":"555-555-5555"}
->
billingAddress

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. The billing_address resource has the following properties:

Show billing_address 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 alphanumeric abbreviation of the region for the billing address.
  • zip: The postal code of the billing address, such as zip, postcode, or Eircode.

Create draft order with custom shipping address

Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.line_items:[{"variant_id":447654529,"quantity":1}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
draft_order.shipping_address:{"first_name":"Bob","last_name":"Norman","address1":"123 Main St","city":"Anytown","province":"ON","country":"Canada","zip":"A1B2C3","phone":"555-555-5555"}
->
shippingAddress

The address to ship the order to. The shipping_address is optional and will not be available on orders that don't require shipping. The shipping_address resource has the following properties:

Show shipping_address 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 alphanumeric abbreviation of the state or province of the shipping address.
  • zip: The zip or postal code of the shipping address.

Create a draft order with a discounted line item

Request body
draft_order
Draft_order resource
Show draft_order properties
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"}}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.

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

Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.line_items:[{"variant_id":447654529,"quantity":1}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
Was this section helpful?
post

/admin/api/2026-07/draft_orders.json

curl -d '{"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}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 201 Created
{
"draft_order": {
"id": 1069920533,
"note": null,
"email": "bob.norman@mail.example.com",
"taxes_included": false,
"currency": "USD",
"invoice_sent_at": null,
"created_at": "2026-07-02T11:07:49-04:00",
"updated_at": "2026-07-02T11:07:49-04:00",
"tax_exempt": false,
"completed_at": null,
"name": "#D5",
"allow_discount_codes_in_checkout?": false,
"b2b?": false,
"status": "open",
"line_items": [
{
"id": 1066630439,
"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": [
{
"rate": 0.06,
"title": "Tax",

Anchor to POST request, Send an invoice
post
Send an invoice

draftOrderInvoiceSend

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.

Anchor to Parameters of Send an invoiceParameters

api_version
string
required
draft_order_id
string
required
Was this section helpful?

Anchor to post-draft-orders-draft-order-id-send-invoice-examplesExamples

Send a customized invoice

Path parameters
draft_order_id=994118539
string
required

Send the default invoice

Path parameters
draft_order_id=994118539
string
required
Was this section helpful?
post

/admin/api/2026-07/draft_orders/994118539/send_invoice.json

curl -d '{"draft_order_invoice":{"to":"first@example.com","from":"j.smith@example.com","bcc":["j.smith@example.com"],"subject":"Apple Computer Invoice","custom_message":"Thank you for ordering!"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/994118539/send_invoice.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 201 Created
{
"draft_order_invoice": {
"to": "first@example.com",
"from": "j.smith@example.com",
"subject": "Apple Computer Invoice",
"custom_message": "Thank you for ordering!",
"bcc": [
"j.smith@example.com"
]
}
}

Anchor to GET request, Retrieves a list of draft orders
get
Retrieves a list of draft orders

draftOrders

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.

Anchor to Parameters of Retrieves a list of draft ordersParameters

api_version
string
required
fields

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

fields

comma-separated list of fields to include in the response

ids

Filter by list of IDs

limit
≤ 250
default 50

Amount of results

since_id

Restrict results to after the specified ID

status
enum
default open

Filter draft orders by their status.

Show status properties

  • open: All open orders (default)

  • invoice_sent: Draft orders for which invoice has been sent to the customer

  • completed: Draft orders that have been completed and turned into an order

updated_at_max

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

updated_at_min

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

Was this section helpful?

Anchor to get-draft-orders-examplesExamples

List all draft orders

Retrieve all draft orders after the specified ID

Query parameters
since_id=123

Restrict results to after the specified ID

Retrieve all draft orders but show only certain properties

Query parameters
fields=created_at,id,name,total-price

comma-separated list of fields to include in the response

Retrieve draft orders last updated after 2005-07-31 15:57:11 in the EDT timezone

Query parameters
updated_at_min=2005-07-31T15:57:11-04:00

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

Was this section helpful?
get

/admin/api/2026-07/draft_orders.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"draft_orders": [
{
"id": 47884561,
"note": null,
"email": null,
"taxes_included": false,
"currency": "USD",
"invoice_sent_at": null,
"created_at": "2023-12-31T19:00:00-05:00",
"updated_at": "2023-12-31T19:00:00-05:00",
"tax_exempt": false,
"completed_at": null,
"name": "#D3",
"allow_discount_codes_in_checkout?": false,
"b2b?": false,
"status": "open",
"line_items": [
{
"id": 396451837,
"variant_id": 39072856,
"product_id": 632910392,
"title": "IPod Nano - 8GB",
"variant_title": "Green",
"sku": "IPOD2008GREEN",
"vendor": "Apple",
"quantity": 1,
"requires_shipping": true,
"taxable": true,
"gift_card": false,
"fulfillment_service": "manual",
"grams": 567,
"tax_lines": [
{
"rate": 0.08,

Anchor to GET request, Receive a single DraftOrder
get
Receive a single DraftOrder

draftOrder

Retrieves a specific draft order

Anchor to Parameters of Receive a single DraftOrderParameters

api_version
string
required
draft_order_id
string
required
fields

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

Was this section helpful?

Anchor to get-draft-orders-draft-order-id-examplesExamples

Get a representation of a single draft order

Path parameters
draft_order_id=994118539
string
required
Was this section helpful?
get

/admin/api/2026-07/draft_orders/994118539.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/994118539.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"draft_order": {
"id": 994118539,
"note": "rush order",
"email": "bob.norman@mail.example.com",
"taxes_included": false,
"currency": "USD",
"invoice_sent_at": null,
"created_at": "2026-07-02T10:36:00-04:00",
"updated_at": "2026-07-02T10:36:00-04:00",
"tax_exempt": false,
"completed_at": null,
"name": "#D2",
"allow_discount_codes_in_checkout?": false,
"b2b?": false,
"status": "open",
"line_items": [
{
"id": 994118539,
"variant_id": 39072856,
"product_id": 632910392,
"title": "IPod Nano - 8GB",
"variant_title": "Green",
"sku": "IPOD2008GREEN",
"vendor": "Apple",
"quantity": 1,
"requires_shipping": true,
"taxable": true,
"gift_card": false,
"fulfillment_service": "manual",
"grams": 567,
"tax_lines": [
{
"rate": 0.06,
"title": "Tax",

Anchor to GET request, Receive a count of all DraftOrders
get
Receive a count of all DraftOrders

draftOrdersCount

Retrieves a count of draft orders

Anchor to Parameters of Receive a count of all DraftOrdersParameters

api_version
string
required
since_id

Count draft orders after the specified ID.

status
default open

Count draft orders that have a given status.

Show status properties

  • open: All open orders (default)

  • invoice_sent: Draft orders for which invoice has been sent to the customer

  • completed: Draft orders that have been completed and turned into an order

updated_at_max

Count draft orders last updated before the specified date (format: 2014-04-25T16:15:47-04:00).

updated_at_min

Count draft orders last updated after the specified date (format: 2014-04-25T16:15:47-04:00).

Was this section helpful?

Anchor to get-draft-orders-count-examplesExamples

Count all draft orders

Was this section helpful?
get

/admin/api/2026-07/draft_orders/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 13
}

Anchor to PUT request, Modify an existing DraftOrder
put
Modify an existing DraftOrder

draftOrderUpdate

Updates a draft order.

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

Caution

If a checkout has been started for a draft order, any update to the draft will unlink the checkout. Checkouts are created but not immediately completed when opening the merchant credit card modal in the admin, and when a buyer opens the invoice URL. This is usually fine, but there is an edge case where a checkout is in progress and the draft is updated before the checkout completes. This will not interfere with the checkout and order creation, but if the link from draft to checkout is broken the draft will remain open even after the order is created.

Anchor to Parameters of Modify an existing DraftOrderParameters

api_version
string
required
draft_order_id
string
required
Was this section helpful?

Anchor to put-draft-orders-draft-order-id-examplesExamples

Set a discount on a draft order

Path parameters
draft_order_id=1012750869
string
required
Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.id:1012750869
read-only

The ID of the draft order.

draft_order.applied_discount:{"description":"Custom discount","value_type":"percentage","value":"10.0","amount":"19.90","title":"Custom"}
->
appliedDiscount

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

Show applied_discount 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.

Add a note to a draft order

Path parameters
draft_order_id=1012750869
string
required
Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.id:1012750869
read-only

The ID of the draft order.

draft_order.note:"Customer contacted us about a custom engraving on this iPod"
->
note

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

Change a line item on a draft order

Path parameters
draft_order_id=1012750869
string
required
Request body
draft_order
Draft_order resource
Show draft_order properties
draft_order.id:1012750869
read-only

The ID of the draft order.

draft_order.line_items:[{"variant_id":447654529,"quantity":1}]
->
lineItems

The product variant line item or custom line item associated to the draft order. Each draft order must include at least one line_item. Note that Draft orders don't currently support subscriptions. Each line_item resource has the following properties:

Show line_items 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 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: The vendor.
  • quantity: The number of products that were purchased.
  • gift_card: Indicates if the product is a gift card. Valid values: true or false.
  • fulfillment_service: The service provider responsible for fulfillment. Valid values are either manual or the name of the provider, for example amazon, shipwire. 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 the applied_discount property.
  • tax_lines: Read only field The calculated rate and amount of taxes for the line item.
    • price: The amount of tax to be charged.
    • rate: The rate of tax to be applied.
    • title: The name of the tax.
  • title: The title of the product or variant. Applicable only to custom line items. Required field.
  • price: The price of the item before discounts have been applied. Applicable only to custom line items. Required field.
  • grams: The weight of the item in grams. Applicable only 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: true or false.
  • sku: A unique identifier for the item in the fulfillment. Applicable only to custom line items.
  • taxable: Whether the product is taxable. Applicable only to custom line items.
Was this section helpful?
put

/admin/api/2026-07/draft_orders/1012750869.json

curl -d '{"draft_order":{"id":1012750869,"applied_discount":{"description":"Custom discount","value_type":"percentage","value":"10.0","amount":"19.90","title":"Custom"}}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/1012750869.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 200 OK
{
"draft_order": {
"taxes_included": false,
"email": "bob.norman@mail.example.com",
"currency": "USD",
"note": "rush order",
"id": 1012750869,
"invoice_sent_at": null,
"created_at": "2026-07-02T10:36:00-04:00",
"updated_at": "2026-07-02T11:07:50-04:00",
"tax_exempt": false,
"completed_at": null,
"name": "#D2",
"allow_discount_codes_in_checkout?": false,
"b2b?": false,
"status": "open",
"line_items": [
{
"id": 294997122,
"variant_id": 39072856,
"product_id": 632910392,
"title": "IPod Nano - 8GB",
"variant_title": "Green",
"sku": "IPOD2008GREEN",
"vendor": "Apple",
"quantity": 1,
"requires_shipping": true,
"taxable": true,
"gift_card": false,
"fulfillment_service": "manual",
"grams": 567,
"tax_lines": [
{
"rate": 0.04,
"title": "GST",

Anchor to PUT request, Complete a draft order
put
Complete a draft order

draftOrderComplete

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.

Anchor to Parameters of Complete a draft orderParameters

api_version
string
required
draft_order_id
string
required
payment_gateway_id

Sets the payment gateway ID. For more information, see the Payments API.

payment_pending

Sets payment pending to true or false.

Show payment_pending properties

  • true: The resulting order will be unpaid and can be captured later.

  • false: The resulting order will be marked as paid through either the default or specified gateway.

Was this section helpful?

Anchor to put-draft-orders-draft-order-id-complete-examplesExamples

Complete a draft order, marking it as pending

Path parameters
draft_order_id=622762746
string
required
Query parameters
payment_pending=true

Sets payment pending to true or false.

Show payment_pending properties

  • true: The resulting order will be unpaid and can be captured later.

  • false: The resulting order will be marked as paid through either the default or specified gateway.

Was this section helpful?
put

/admin/api/2026-07/draft_orders/622762746/complete.json

curl -X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/622762746/complete.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"draft_order": {
"id": 622762746,
"note": "rush order",
"email": "bob.norman@mail.example.com",
"taxes_included": false,
"currency": "USD",
"invoice_sent_at": null,
"created_at": "2026-07-02T10:36:00-04:00",
"updated_at": "2026-07-02T11:07:52-04:00",
"tax_exempt": false,
"completed_at": "2026-07-02T11:07:52-04:00",
"name": "#D1",
"allow_discount_codes_in_checkout?": false,
"b2b?": false,
"status": "completed",
"line_items": [
{
"id": 466157049,
"variant_id": 39072856,
"product_id": 632910392,
"title": "IPod Nano - 8GB",
"variant_title": "Green",
"sku": "IPOD2008GREEN",
"vendor": "Apple",
"quantity": 1,
"requires_shipping": true,
"taxable": true,
"gift_card": false,
"fulfillment_service": "manual",
"grams": 567,
"tax_lines": [
{
"rate": 0.06,
"title": "Tax",

Anchor to DELETE request, Remove an existing DraftOrder
del
Remove an existing DraftOrder

draftOrderDelete

Deletes a draft order

Anchor to Parameters of Remove an existing DraftOrderParameters

api_version
string
required
draft_order_id
string
required
Was this section helpful?

Anchor to delete-draft-orders-draft-order-id-examplesExamples

Permanently delete a draft order

Path parameters
draft_order_id=994118539
string
required
Was this section helpful?
del

/admin/api/2026-07/draft_orders/994118539.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2026-07/draft_orders/994118539.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{}