Create a new DraftOrder

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 }

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.

请求参数

Path 参数

api_version

string

必需

Query 参数

customer_id

string

可选

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

use_customer_default_address

string

可选

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

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢201Create a new DraftOrder

application/json

Body

draft_order

object (DraftOrder)

可选

string

可选

The ID of the draft order.

order_id

string

可选

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

name

string

可选

Name of the draft order.

customer

string

可选

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

string

可选

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:

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 two-letter abbreviation of the state or province of the shipping address.
zip: The zip or postal code of the shipping address.

billing_address

string

可选

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:

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

note

string

可选

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

note_attributes

string

可选

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.

示例值:

{"name":"custom name","value":"custom value"}

string

可选

The customer's email address.

currency

string

可选

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

invoice_sent_at

string

可选

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

invoice_url

string

可选

The URL for the invoice.

line_items

string

可选

The product variant line item or custom line item associated to the draft order.
Each draft order must include at least one line_item.
Each line_item resource has the following 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.

payment_terms

string

只读可选

The terms and conditions under which a payment should be processed.

amount: The amount that is owed according to the payment terms.
currency: The presentment currency for the payment.
payment_terms_name: The name of the selected payment terms template for the draft order.
payment_terms_type: The type of selected payment terms template for the draft order.
due_in_days: The number of days between the invoice date and due date that is defined in the selected payment terms template.
payment_schedules: An array of schedules associated to the payment terms.

amount: The amount that is owed according to the payment terms.
currency: The presentment currency for the payment.
issued_at: The date and time when the payment terms were initiated.
due_at: The date and time when the payment is due. Calculated based on issued_at and due_in_days or a customized fixed date if the type is fixed.
completed_at: The date and time when the purchase is completed. Returns null initially and updates when the payment is captured.
expected_payment_method: The name of the payment method gateway.

shipping_line

string

可选

The shipping method used. Each shipping_line resource has the following properties:

custom: Whether this is a regular shipping line or custom shipping line.
handle: The handle of the shipping rate which was selected and applied. Required for regular shipping lines.
title: The title of the shipping method. Required for custom shipping lines. (maximum: 255 characters)
price: The price of the shipping method. Required for custom shipping lines.

source_name

string

可选

The source of the checkout. To use this field for sales attribution, you need to register the channels that your app is managing.
You can register the channels that your app is managing by completing the Order Attribution Access Form.
After you've submited the form, you'll need to wait for your request to be processed by Shopify. You can find a list of your channels in the Partner Dashboard, in your app's Marketplace extension.
You can specify a handle as the source_name value in your request.

tags

string

可选

A comma-seperated list of additional short descriptors, commonly used for filtering and searching.
Each individual tag is limited to 40 characters in length. For example, tags: "tag1","tag2","tag3".

tax_exempt

string

可选

Whether taxes are exempt for the draft order. If set to false,
then Shopify refers to the taxable field for each line_item.
If a customer is applied to the draft order, then Shopify uses the customer's tax_exempt field instead.

tax_exemptions

enum<string>

可选

Whether the customer is exempt from paying specific taxes on their order. Canadian taxes only.

枚举值:

EXEMPT_ALLCA_STATUS_CARD_EXEMPTIONCA_DIPLOMAT_EXEMPTIONCA_BC_RESELLER_EXEMPTIONCA_MB_RESELLER_EXEMPTIONCA_SK_RESELLER_EXEMPTIONCA_BC_COMMERCIAL_FISHERY_EXEMPTIONCA_MB_COMMERCIAL_FISHERY_EXEMPTIONCA_NS_COMMERCIAL_FISHERY_EXEMPTIONCA_PE_COMMERCIAL_FISHERY_EXEMPTIONCA_SK_COMMERCIAL_FISHERY_EXEMPTIONCA_BC_PRODUCTION_AND_MACHINERY_EXEMPTIONCA_SK_PRODUCTION_AND_MACHINERY_EXEMPTIONCA_BC_SUB_CONTRACTOR_EXEMPTIONCA_SK_SUB_CONTRACTOR_EXEMPTIONCA_BC_CONTRACTOR_EXEMPTIONCA_SK_CONTRACTOR_EXEMPTIONCA_ON_PURCHASE_EXEMPTIONCA_MB_FARMER_EXEMPTIONCA_NS_FARMER_EXEMPTIONCA_SK_FARMER_EXEMPTION

示例值:

CA_STATUS_CARD_EXEMPTIONCA_BC_RESELLER_EXEMPTION

tax_lines

string

只读可选

An array of tax line resources, each of which details a tax applicable to the order. Each tax_lines resource has the following properties:

price: The amount of tax to be charged.
rate: The rate of tax to be applied.
title: The name of the tax.

示例值:

{"price":11.94,"rate":0.06,"title":"State Tax"}

applied_discount

string

可选

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:

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.

taxes_included

string

可选

Whether taxes are included in the order subtotal.
Valid values: true or false.

total_tax

string

可选

The sum of all the taxes applied to the order.

subtotal_price

string

可选

The price of the order before shipping and taxes.

total_price

string

可选

The sum of all the prices of all the items in the order,
including taxes and discounts.

completed_at

string

可选

The date and time (ISO 8601 format) when the order is created and the draft order is completed.

created_at

string

可选

The date and time (ISO 8601 format) when the order was created in Shopify.

updated_at

string

可选

The date and time (ISO 8601 format) when the order was last modified.

status

enum<string>

可选

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:

枚举值:

openinvoice_sentcompleted

示例

Create a draft order with a discountCreate a draft order with a percent discount on Create custom draft orderCreate draft order with custom billing linesCreate draft order with custom shipping linesCreate a draft order with a discounted line itemCreate a simple draft order with only a product variant ID.

{
  "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
      }
    }
  }
}

修改于 2023-01-29 12:00:32

Retrieves a list of abandoned checkouts

Retrieves a list of draft orders