Creates a draft order.
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.
<code> > 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.</code>
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 ShopBase 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 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
Request body
Example request
{
"access_key": "68778783ad298f1c80c3bafcddeea02f",
"additional_information": {
"IPS": "FPT",
"city": "Hanoi",
"country": "example country",
"hostname": "example host name",
"latitude": "27.683528",
"longitude": "27.683528",
"organization": "example organization",
"region": "VN",
"timezone": "7"
},
"applied_discount": {
"amount": "10",
"description": "example desc",
"title": "Super discount",
"value": "example value"
},
"balance": 10000,
"billing_address": {
"address1": "123 Fake Street",
"city": "Fakecity",
"country": "Vietnam",
"country_code": "VN",
"country_name": "Viet nam",
"cpf_or_cnpj_number": "CPF: 231.234.234-23, CNPJ: 23.123.423/4234-24",
"first_name": "John",
"last_name": "Smith",
"name": "example name",
"province": "Ontario",
"zip": "K2P 1L4"
},
"cancel_reason": "customer",
"cancelled_at": "2019-04-22T11:00:00-05:00",
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"chargeback_amount": 1000,
"chargeback_deadline_at": "2019-04-22T11:00:00-05:00",
"checkout_token": "68778783ad298f1c80c3bafcddeea02f",
"client_details": {
"accept_language": "en-US,en;q=0.9",
"browser_height": 1320,
"browser_ip": "216.191.105.146",
"browser_width": 1280,
"session_hash": "9ad4d1f4e6a8977b9dd98eed1e477643",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36"
},
"closed_at": "2019-04-22T11:00:00-05:00",
"created_at": "2019-04-22T11:00:00-05:00",
"created_at_in_timezone": "2019-04-22T11:00:00-05:00",
"currency": "USD",
"customer_locale": "en-CA",
"discount_applications": [
{
"allocation_method": "across",
"code": "SUMMERSALE",
"description": "my scripted discount",
"discount_type": "fixed_amount",
"is_applied_entire_order": true,
"target_selection": "all",
"target_type": "line_item",
"title": "custom discount",
"type": "script",
"value": 10,
"value_type": "fixed_amount"
}
],
"discount_code": [
{
"amount": 30,
"code": "SPRING30",
"type": "fixed_amount"
}
],
"email": "bob.norman@hostmail.com",
"financial_status": "pending",
"fulfillments": [
{
"id": 255858046,
"name": "255858046",
"notify_customer": true,
"order_id": 450789469,
"service": "255858046",
"shipment_status": "confirmed",
"status": "255858046",
"tracking_company": "4PX",
"tracking_number": "1Z2345",
"tracking_numbers": [
"112345Z2345"
],
"tracking_url": "http://example.com/etracking/tracking.cgi?InquiryNumber1=1Z2345&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track",
"tracking_urls": [
"http://track-example.com/startairmail.php?code=112345Z2345"
],
"variant_inventory_management": "shopbase"
}
],
"id": 450789469,
"is_in_post_purchase": true,
"line_items": [
{
"discount_amount": 1,
"fulfillable_quantity": 1,
"fulfillment_service": "amazon",
"fulfillment_status": "fulfilled",
"image_src": "https://example.com/img.jpg",
"item_discount_price": 20,
"line_item_discount_amount": 20,
"line_item_discount_price": 100,
"line_item_price": 100,
"line_item_price_after_discount": 20,
"line_item_price_before_discount": 20,
"line_item_price_with_explicit_discount": 10,
"line_item_weight": 10,
"not_explicit_discount_price": 2,
"order_id": 1,
"price": 225,
"product_id": 1,
"product_type": "1",
"quantity": 1000,
"raw_price": 20,
"raw_weight": 10,
"requires_shipping": true,
"shipping_rate": {
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"id": 43531,
"price": 8,
"title": "Small Packet International Air",
"type": "weight_based, price_based, item_based",
"variant_id": 123213213123
},
"sku": "IPOD2008GREEN",
"tags": "Emotive, Flash Memory, MP3, Music",
"tax_amount": 20,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"tax_rate": 1,
"title": "IPOD2008GREEN",
"total_item_discount_price": 10,
"total_line_with_discount_price": 10,
"total_tax_amount": 10,
"variant_id": 1,
"variant_title": "IPOD2008GREEN",
"weight": 1.5,
"weight_unit": "kg"
}
],
"name": "example name",
"not_explicit_discount": 123,
"note": "Customer changed their mind.",
"order_number": 100,
"order_status_url": "https://checkout.shopbase.com/112233/checkouts/4207896aad57dfb159/thank_you_token?key=753621327b9e8a64789651bf221dfe35",
"original_total_price": 10001203,
"payment_gateway": "paypal",
"phone": "+557734881234",
"post_purchase_timeout_at": "2019-04-22T11:00:00-05:00",
"previous_shipping_fee": 10000,
"processed_at": "2019-04-22T11:00:00-05:00",
"referring_site": "http://www.anexample.com",
"refunds": [
{
"id": 92738740,
"note": "Item was damaged during shipping",
"order_adjustments": [
{
"amount": -8,
"kind": "shipping_refund",
"order_id": 171016912932,
"reason": "Shipping refund"
}
],
"order_id": 171016912932,
"refund_line_items": [
{
"discount_amount": 10.99,
"line_item": {
"discount_amount": 1,
"fulfillable_quantity": 1,
"fulfillment_service": "amazon",
"fulfillment_status": "fulfilled",
"image_src": "https://example.com/img.jpg",
"item_discount_price": 20,
"line_item_discount_amount": 20,
"line_item_discount_price": 100,
"line_item_price": 100,
"line_item_price_after_discount": 20,
"line_item_price_before_discount": 20,
"line_item_price_with_explicit_discount": 10,
"line_item_weight": 10,
"not_explicit_discount_price": 2,
"order_id": 1,
"price": 225,
"product_id": 1,
"product_type": "1",
"quantity": 1000,
"raw_price": 20,
"raw_weight": 10,
"requires_shipping": true,
"shipping_rate": {
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"id": 43531,
"price": 8,
"title": "Small Packet International Air",
"type": "weight_based, price_based, item_based",
"variant_id": 123213213123
},
"sku": "IPOD2008GREEN",
"tags": "Emotive, Flash Memory, MP3, Music",
"tax_amount": 20,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"tax_rate": 1,
"title": "IPOD2008GREEN",
"total_item_discount_price": 10,
"total_line_with_discount_price": 10,
"total_tax_amount": 10,
"variant_id": 1,
"variant_title": "IPOD2008GREEN",
"weight": 1.5,
"weight_unit": "kg"
},
"line_item_id": 128323456,
"quantity": 2,
"restock_type": "return",
"subtotal": 10.99,
"title": "Title",
"total_refund": 2.67,
"total_tax": 2.67,
"variant_title": "Variant title"
}
],
"restock": true,
"shipping": {
"amount": 10,
"full_refund": true
},
"transactions": [
{
"amount": 10,
"authorization": "ch_1AtJu6CktlpKSclI4zjeQb2t",
"currency": "USD",
"error_code": "invalid_cvc",
"gateway": "shopbase_payments",
"id": 999225661,
"kind": "capture",
"message": "Marked the Cash on Delivery (COD) payment as received",
"order_id": 450789469,
"source_name": "web",
"status": "success",
"test": true
}
],
"user_id": 238478920
}
],
"shipping_address": {
"address1": "123 Fake Street",
"city": "Fakecity",
"country": "Vietnam",
"country_code": "VN",
"country_name": "Viet nam",
"cpf_or_cnpj_number": "CPF: 231.234.234-23, CNPJ: 23.123.423/4234-24",
"first_name": "John",
"last_name": "Smith",
"name": "example name",
"province": "Ontario",
"zip": "K2P 1L4"
},
"shipping_discount": 2,
"shipping_fee": 10,
"shipping_lines": [
{
"carrier_identifier": "third_party_carrier_identifier",
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"discounted_price": 4,
"fulfillment_service": "third_party_fulfillment_service_id",
"price": 4,
"source": "canada_post",
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"title": "Small Packet International Air"
}
],
"shipping_tax": 2,
"shop_id": 123123,
"source_name": "web",
"subtotal_price": 123,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"taxes_included": true,
"token": "68778783ad298f1c80c3bafcddeea02f",
"total_discounts": 1,
"total_line_items_discount": 123,
"total_line_items_price": 123,
"total_price": 100000,
"total_quantity": 100,
"total_shipping": 10,
"total_tax": 123,
"total_tip_received": 4.87,
"total_weight": 10,
"updated_at": "2019-04-22T11:00:00-05:00",
"weight_unit": "Kg"
}Response
OK
Example response
{
"draft_order": {
"access_key": "68778783ad298f1c80c3bafcddeea02f",
"additional_information": {
"IPS": "FPT",
"city": "Hanoi",
"country": "example country",
"hostname": "example host name",
"latitude": "27.683528",
"longitude": "27.683528",
"organization": "example organization",
"region": "VN",
"timezone": "7"
},
"applied_discount": {
"amount": "10",
"description": "example desc",
"title": "Super discount",
"value": "example value"
},
"balance": 10000,
"billing_address": {
"address1": "123 Fake Street",
"city": "Fakecity",
"country": "Vietnam",
"country_code": "VN",
"country_name": "Viet nam",
"cpf_or_cnpj_number": "CPF: 231.234.234-23, CNPJ: 23.123.423/4234-24",
"first_name": "John",
"last_name": "Smith",
"name": "example name",
"province": "Ontario",
"zip": "K2P 1L4"
},
"cancel_reason": "customer",
"cancelled_at": "2019-04-22T11:00:00-05:00",
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"chargeback_amount": 1000,
"chargeback_deadline_at": "2019-04-22T11:00:00-05:00",
"checkout_token": "68778783ad298f1c80c3bafcddeea02f",
"client_details": {
"accept_language": "en-US,en;q=0.9",
"browser_height": 1320,
"browser_ip": "216.191.105.146",
"browser_width": 1280,
"session_hash": "9ad4d1f4e6a8977b9dd98eed1e477643",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36"
},
"closed_at": "2019-04-22T11:00:00-05:00",
"created_at": "2019-04-22T11:00:00-05:00",
"created_at_in_timezone": "2019-04-22T11:00:00-05:00",
"currency": "USD",
"customer_locale": "en-CA",
"discount_applications": [
{
"allocation_method": "across",
"code": "SUMMERSALE",
"description": "my scripted discount",
"discount_type": "fixed_amount",
"is_applied_entire_order": true,
"target_selection": "all",
"target_type": "line_item",
"title": "custom discount",
"type": "script",
"value": 10,
"value_type": "fixed_amount"
}
],
"discount_code": [
{
"amount": 30,
"code": "SPRING30",
"type": "fixed_amount"
}
],
"email": "bob.norman@hostmail.com",
"financial_status": "pending",
"fulfillments": [
{
"id": 255858046,
"name": "255858046",
"notify_customer": true,
"order_id": 450789469,
"service": "255858046",
"shipment_status": "confirmed",
"status": "255858046",
"tracking_company": "4PX",
"tracking_number": "1Z2345",
"tracking_numbers": [
"112345Z2345"
],
"tracking_url": "http://example.com/etracking/tracking.cgi?InquiryNumber1=1Z2345&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track",
"tracking_urls": [
"http://track-example.com/startairmail.php?code=112345Z2345"
],
"variant_inventory_management": "shopbase"
}
],
"id": 450789469,
"is_in_post_purchase": true,
"line_items": [
{
"discount_amount": 1,
"fulfillable_quantity": 1,
"fulfillment_service": "amazon",
"fulfillment_status": "fulfilled",
"image_src": "https://example.com/img.jpg",
"item_discount_price": 20,
"line_item_discount_amount": 20,
"line_item_discount_price": 100,
"line_item_price": 100,
"line_item_price_after_discount": 20,
"line_item_price_before_discount": 20,
"line_item_price_with_explicit_discount": 10,
"line_item_weight": 10,
"not_explicit_discount_price": 2,
"order_id": 1,
"price": 225,
"product_id": 1,
"product_type": "1",
"quantity": 1000,
"raw_price": 20,
"raw_weight": 10,
"requires_shipping": true,
"shipping_rate": {
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"id": 43531,
"price": 8,
"title": "Small Packet International Air",
"type": "weight_based, price_based, item_based",
"variant_id": 123213213123
},
"sku": "IPOD2008GREEN",
"tags": "Emotive, Flash Memory, MP3, Music",
"tax_amount": 20,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"tax_rate": 1,
"title": "IPOD2008GREEN",
"total_item_discount_price": 10,
"total_line_with_discount_price": 10,
"total_tax_amount": 10,
"variant_id": 1,
"variant_title": "IPOD2008GREEN",
"weight": 1.5,
"weight_unit": "kg"
}
],
"name": "example name",
"not_explicit_discount": 123,
"note": "Customer changed their mind.",
"order_number": 100,
"order_status_url": "https://checkout.shopbase.com/112233/checkouts/4207896aad57dfb159/thank_you_token?key=753621327b9e8a64789651bf221dfe35",
"original_total_price": 10001203,
"payment_gateway": "paypal",
"phone": "+557734881234",
"post_purchase_timeout_at": "2019-04-22T11:00:00-05:00",
"previous_shipping_fee": 10000,
"processed_at": "2019-04-22T11:00:00-05:00",
"referring_site": "http://www.anexample.com",
"refunds": [
{
"id": 92738740,
"note": "Item was damaged during shipping",
"order_adjustments": [
{
"amount": -8,
"kind": "shipping_refund",
"order_id": 171016912932,
"reason": "Shipping refund"
}
],
"order_id": 171016912932,
"refund_line_items": [
{
"discount_amount": 10.99,
"line_item": {
"discount_amount": 1,
"fulfillable_quantity": 1,
"fulfillment_service": "amazon",
"fulfillment_status": "fulfilled",
"image_src": "https://example.com/img.jpg",
"item_discount_price": 20,
"line_item_discount_amount": 20,
"line_item_discount_price": 100,
"line_item_price": 100,
"line_item_price_after_discount": 20,
"line_item_price_before_discount": 20,
"line_item_price_with_explicit_discount": 10,
"line_item_weight": 10,
"not_explicit_discount_price": 2,
"order_id": 1,
"price": 225,
"product_id": 1,
"product_type": "1",
"quantity": 1000,
"raw_price": 20,
"raw_weight": 10,
"requires_shipping": true,
"shipping_rate": {
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"id": 43531,
"price": 8,
"title": "Small Packet International Air",
"type": "weight_based, price_based, item_based",
"variant_id": 123213213123
},
"sku": "IPOD2008GREEN",
"tags": "Emotive, Flash Memory, MP3, Music",
"tax_amount": 20,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"tax_rate": 1,
"title": "IPOD2008GREEN",
"total_item_discount_price": 10,
"total_line_with_discount_price": 10,
"total_tax_amount": 10,
"variant_id": 1,
"variant_title": "IPOD2008GREEN",
"weight": 1.5,
"weight_unit": "kg"
},
"line_item_id": 128323456,
"quantity": 2,
"restock_type": "return",
"subtotal": 10.99,
"title": "Title",
"total_refund": 2.67,
"total_tax": 2.67,
"variant_title": "Variant title"
}
],
"restock": true,
"shipping": {
"amount": 10,
"full_refund": true
},
"transactions": [
{
"amount": 10,
"authorization": "ch_1AtJu6CktlpKSclI4zjeQb2t",
"currency": "USD",
"error_code": "invalid_cvc",
"gateway": "shopbase_payments",
"id": 999225661,
"kind": "capture",
"message": "Marked the Cash on Delivery (COD) payment as received",
"order_id": 450789469,
"source_name": "web",
"status": "success",
"test": true
}
],
"user_id": 238478920
}
],
"shipping_address": {
"address1": "123 Fake Street",
"city": "Fakecity",
"country": "Vietnam",
"country_code": "VN",
"country_name": "Viet nam",
"cpf_or_cnpj_number": "CPF: 231.234.234-23, CNPJ: 23.123.423/4234-24",
"first_name": "John",
"last_name": "Smith",
"name": "example name",
"province": "Ontario",
"zip": "K2P 1L4"
},
"shipping_discount": 2,
"shipping_fee": 10,
"shipping_lines": [
{
"carrier_identifier": "third_party_carrier_identifier",
"code": "weight_based_47925+weight_based_47926+weight_based_47928",
"discounted_price": 4,
"fulfillment_service": "third_party_fulfillment_service_id",
"price": 4,
"source": "canada_post",
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"title": "Small Packet International Air"
}
],
"shipping_tax": 2,
"shop_id": 123123,
"source_name": "web",
"subtotal_price": 123,
"tax_lines": [
{
"price": 25.81,
"rate": 0.13,
"title": "HST"
}
],
"taxes_included": true,
"token": "68778783ad298f1c80c3bafcddeea02f",
"total_discounts": 1,
"total_line_items_discount": 123,
"total_line_items_price": 123,
"total_price": 100000,
"total_quantity": 100,
"total_shipping": 10,
"total_tax": 123,
"total_tip_received": 4.87,
"total_weight": 10,
"updated_at": "2019-04-22T11:00:00-05:00",
"weight_unit": "Kg"
}
}