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.
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.
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.
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.
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 }
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
.
curl --location --request POST 'https://demo.myshopify.com//admin/api//draft_orders.json'
customer
resource, seeshipping_address
is optional and will not be available on orders that don't require shipping. The shipping_address
resource has the following properties:billing_address
resource has the following properties:name
and value
keys.line_item
.line_item
resource has the following properties:true
indicates a custom line item.false
indicates a product variant line item.null
for a custom line item.Custom
for custom line items created via the API.true
or false
.manual
or the name of the provider, for example amazon, shipwire. Defaults to manual
for custom line items.applied_discount
property.true
or false.
issued_at
and due_in_days
or a customized fixed date if the type is fixed.shipping_line
resource has the following properties:source_name
value in your request.tags: "tag1","tag2","tag3"
.false
,taxable
field for each line_item
.tax_exempt
field instead.tax_lines
resource has the following properties:applied_discount
resource and each draft order line item can have its own applied_discount
.applied_discount
resource has the following properties:fixed_amount
, then it corresponds to a fixed dollar amount. If the type is percentage
, then it corresponds to percentage.percentage
, fixed_amount
.value_type
. For more information, see Applying discounts.true
or false
.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:
{
"draft_order": {
"id": 1069920479,
"note": null,
"email": "bob.norman@mail.example.com",
"taxes_included": false,
"currency": "USD",
"invoice_sent_at": null,
"created_at": "2023-01-03T12:58:43-05:00",
"updated_at": "2023-01-03T12:58:43-05:00",
"tax_exempt": false,
"completed_at": null,
"name": "#D5",
"status": "open",
"line_items": [
{
"id": 1066630384,
"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/1066630384"
}
],
"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://jsmith.myshopify.com/548380009/invoices/b21e68f2f1e19263509b19a8286d2d09",
"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",
"presentment_currency": "USD",
"total_line_items_price_set": {
"shop_money": {
"amount": "40.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "40.00",
"currency_code": "USD"
}
},
"total_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "USD"
}
},
"subtotal_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "USD"
}
},
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"total_discounts_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"payment_terms": null,
"admin_graphql_api_id": "gid://shopify/DraftOrder/1069920479",
"customer": {
"id": 207119551,
"email": "bob.norman@mail.example.com",
"accepts_marketing": false,
"created_at": "2023-01-03T12:56:35-05:00",
"updated_at": "2023-01-03T12:56:35-05: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,
"tags": "",
"last_order_name": "#1001",
"currency": "USD",
"phone": "+16136120707",
"accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
"marketing_opt_in_level": null,
"tax_exemptions": [],
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": "2004-06-13T11:57:11-04:00"
},
"sms_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": "2023-01-03T12:56:35-05:00",
"consent_collected_from": "OTHER"
},
"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
}
}
}
}