Retrieve a list of orders

app_id

string

只读可选

The ID of the app that created the order.

billing_address

object (Customer Address)

可选

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. It 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, town, or village 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 format) 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 region (for example, province, state, or prefecture) of the billing address.
province_code: The two-letter abbreviation of the region of the billing address.
zip: The postal code (for example, zip, postcode, or Eircode) of the billing address.

browser_ip

string <ip>

只读可选

The IP address of the browser used by the customer when they placed the order. Both IPv4 and IPv6 are supported.

buyer_accepts_marketing

string

可选

Whether the customer consented to receive email updates from the shop.

cancel_reason

string

可选

The reason why the order was canceled. Valid values:

customer: The customer canceled the order.
fraud: The order was fraudulent.
inventory: Items in the order were not in inventory.
declined: The payment was declined.
other: A reason not in this list.

cancelled_at

string <ISO_8601>

只读可选

The date and time when the order was canceled. Returns null if the order isn't canceled.

cart_token

string

只读可选

A unique value when referencing the cart that's associated with the order.

checkout_token

string

只读可选

A unique value when referencing the checkout that's associated with the order.

client_details

string

只读可选

Information about the browser that the customer used when they placed their order:

accept_language: The languages and locales that the browser understands.
browser_height: The browser screen height in pixels, if available.
browser_ip: The browser IP address.
browser_width: The browser screen width in pixels, if available.
session_hash: A hash of the session.
user_agent: Details of the browsing client, including software and operating versions.

closed_at

string <ISO_8601>

只读可选

The date and time (ISO 8601 format) when the order was closed. Returns null if the order isn't closed.

company

string

只读可选

Represents information about the purchasing company for the order. null will be returned if there is no purchasing company.

created_at

string <ISO_8601>

只读可选

The autogenerated date and time
(ISO 8601 format)
when the order was created in Shopify.
The value for this property cannot be changed.

currency

string <ISO_4217>

只读可选

The three-letter code (ISO 4217 format) for the shop currency.

current_total_discounts

string

只读可选

The current total discounts on the order in the shop currency. The value of this field reflects order edits, returns, and refunds.

current_total_discounts_set

string

只读可选

The current total discounts on the order in shop and presentment currencies. The amount values associated with this field reflect order edits, returns, and refunds.

current_total_duties_set

string

只读可选

The current total duties charged on the order in shop and presentment currencies. The amount values associated with this field reflect order edits, returns, and refunds.

current_total_price

string

只读可选

The current total price of the order in the shop currency. The value of this field reflects order edits, returns, and refunds.

current_total_price_set

string

只读可选

The current total price of the order in shop and presentment currencies. The amount values associated with this field reflect order edits, returns, and refunds.

current_subtotal_price

string

只读可选

The current subtotal price of the order in the shop currency. The value of this field reflects order edits, returns, and refunds.

current_subtotal_price_set

string

只读可选

The current subtotal price of the order in shop and presentment currencies. The amount values associated with this field reflect order edits, returns, and refunds.

current_total_tax

string

只读可选

The current total taxes charged on the order in the shop currency. The value of this field reflects order edits, returns, or refunds.

current_total_tax_set

string

只读可选

The current total taxes charged on the order in shop and presentment currencies. The amount values associated with this field reflect order edits, returns, and refunds.

customer

object (Customer)

可选

Information about the customer. The order might not have a customer and apps should not depend on the existence of a customer object. This value might be null if the order was created through Shopify POS. For more information about the customer object, see the Customer resource.

customer_locale

string

只读可选

The two or three-letter language code, optionally followed by a region modifier.

discount_applications

enum<string>

只读可选

An ordered list of stacked discount applications.

The discount_applications property includes 3 types: discount_code, manual, and script. All 3 types share a common structure and have some type specific attributes.

allocation_method: The method by which the discount application value has been allocated to entitled lines. Valid values:
- across: The value is spread across all entitled lines.
- each: The value is applied onto every entitled line.
- one: The value is applied onto a single line.
code: The discount code that was used to apply the discount. Available only for discount code applications.
description: The description of the discount application, as defined by the merchant or the Shopify Script. Available only for manual and script discount applications.
target_selection: The lines on the order, of the type defined by target_type, that the discount is allocated over. Valid values:
- all: The discount is allocated onto all lines,
- entitled: The discount is allocated only onto lines it is entitled for.
- explicit: The discount is allocated onto explicitly selected lines.
target_type: The type of line on the order that the discount is applicable on. Valid values:
- line_item: The discount applies to line items.
- shipping_line: The discount applies to shipping lines.
title: The title of the discount application, as defined by the merchant. Available only for manual discount applications.
type: The discount application type. Valid values:
- automatic: The discount was applied automatically, such as by a Buy X Get Y automatic discount.
- discount_code: The discount was applied by a discount code.
- manual: The discount was manually applied by the merchant (for example, by using an app or creating a draft order).
- script: The discount was applied by a Shopify Script.
value: The value of the discount application as a decimal. This represents the intention of the discount application. For example, if the intent was to apply a 20% discount, then the value will be 20.0. If the intent was to apply a $15 discount, then the value will be 15.0.
value_type: The type of the value.

枚举值:

acrosseachoneallentitledexplicitline_itemshipping_lineautomaticdiscount_codemanualscriptfixed_amountpercentage

discount_codes

enum<string>

可选

A list of discounts applied to the order. Each discount object includes the following properties:

amount: The amount that's deducted from the order total. When you create an order, this value is the percentage or monetary amount to deduct. After the order is created, this property returns the calculated amount.
code: When the associated discount application is of type code, this property returns the discount code that was entered at checkout. Otherwise this property returns the title of the discount that was applied.
type: The type of discount. Default value: fixed_amount.

枚举值:

amountcodefixed_amount</code>: Applies <code>amount</code> as a unit of the store's currency. For example, if <code>amountpercentage</code>: Applies a discount of <code>amountshipping</code>: Applies a free shipping discount on orders that have a shipping rate less than or equal to <code>amount</code>. For example, if <code>amount

示例值:

{"code":"SPRING30","amount":"30.00","type":"fixed_amount"}

email

string <email>

可选

The customer's email address.

estimated_taxes

string

可选

Whether taxes on the order are estimated. Many factors can change between the
time a customer places an order and the time the order is shipped, which could affect the calculation
of taxes. This property returns false when taxes on the order are finalized and aren't subject
to any changes.

financial_status

string

可选

The status of payments associated with the order. Can only be set when the order is created. Valid values:

pending: The payments are pending. Payment might fail in this state. Check again to confirm whether the payments have been paid successfully.
authorized: The payments have been authorized.
partially_paid: The order has been partially paid.
paid: The payments have been paid.
partially_refunded: The payments have been partially refunded.
refunded: The payments have been refunded.
voided: The payments have been voided.

fulfillments

string

可选

An array of fulfillments associated with the order. For more information, see the Fulfillment API.

示例值:

{"created_at":"2012-03-13T16:09:54-04:00","id":255858046,"order_id":450789469,"status":"failure","tracking_company":"USPS","tracking_number":"1Z2345","updated_at":"2012-05-01T14:22:25-04:00"}

fulfillment_status

string

可选

The order's status in terms of fulfilled line items. You can use the FulfillmentOrder resource for a more granular view. Valid values:

fulfilled: Every line item in the order has been fulfilled.
null: None of the line items in the order have been fulfilled.
partial: At least one line item in the order has been fulfilled.
restocked: Every line item in the order has been restocked and the order canceled.

gateway

string

已废弃

The payment gateway used.

id

string

只读可选

The ID of the order, used for API purposes.
This is different from the order_number property, which is the ID
used by the shop owner and customer.'

landing_site

string <url>

只读可选

The URL for the page where the buyer landed when they entered the shop.

line_items

string

必需

A list of line item objects, each containing information about an item in the order. Each object has the following properties:

fulfillable_quantity: The amount available to fulfill, calculated as follows:

quantity - max(refunded_quantity, fulfilled_quantity) - pending_fulfilled_quantity - open_fulfilled_quantity

fulfillment_service: The service provider that's fulfilling the item. Valid values: manual, or the name of the provider, such as amazon or shipwire. Multi-managed inventory introduced a breaking change to this field. Fulfillment services will all be opted into SKU sharing in 2023-04. This field is due to be deprecated. Consider using ' "FulfillmentOrder#assigned_location instead.
fulfillment_status: How far along an order is in terms line items fulfilled. Valid values: null, fulfilled, partial, and not_eligible.
grams: The weight of the item in grams.
id: The ID of the line item.
price: The price of the item before discounts have been applied in the shop currency.
price_set: The price of the line item in shop and presentment currencies.
product_id: The ID of the product that the line item belongs to. Can be null if the original product associated with the order is deleted at a later date.
quantity: The number of items that were purchased.
requires_shipping: Whether the item requires shipping.
sku: The item's SKU (stock keeping unit).
title: The title of the product.
variant_id: The ID of the product variant.
variant_title: The title of the product variant.
vendor: The name of the item's supplier.
name: The name of the product variant.
gift_card: Whether the item is a gift card. If true, then the item is not taxed or considered for shipping charges.
properties: An array of custom information for the item that has been added to the cart. Often used to provide product customization options.
taxable: Whether the item was taxable.
tax_lines: A list of tax line objects, each of which details a tax applied to the item.
- title: The name of the tax.
- price: The amount added to the order for this tax in the shop currency.
- price_set: The amount added to the order for this tax in shop and presentment currencies.
- rate: The tax rate applied to the order to calculate the tax price.
- channel_liable: Whether the channel that submitted the tax line is liable for remitting. A value of null indicates unknown liability for the tax line.
tip_payment_gateway: The payment gateway used to tender the tip, such as shopify_payments. Present only on tips.
tip_payment_method: The payment method used to tender the tip, such as Visa. Present only on tips.
total_discount: The total amount of the discount allocated to the line item in the shop currency. This field must be explicitly set using draft orders, Shopify scripts, or the API. Instead of using this field, Shopify recommends using discount_allocations, which provides the same information.
total_discount_set: The total amount allocated to the line item in the presentment currency. Instead of using this field, Shopify recommends using discount_allocations, which provides the same information.
discount_allocations: An ordered list of amounts allocated by discount applications. Each discount allocation is associated with a particular discount application.
- amount: The discount amount allocated to the line in the shop currency.
- discount_application_index: The index of the associated discount application in the order's discount_applications list.
- amount_set: The discount amount allocated to the line item in shop and presentment currencies.
origin_location: The location of the line item’s fulfillment origin. This field is due to be deprecated. Consider using ' "FulfillmentOrder#assigned_location_id instead.
- id: The location ID of the line item’s fulfillment origin. Used by Shopify to calculate applicable taxes. This is not the ID of the location where the order was placed. You can use the FulfillmentOrder resource to determine the location an item will be sourced from.
- country_code: The two-letter code (ISO 3166-1 format) for the country of the item's supplier.
- province_code: The two-letter abbreviation for the region of the item's supplier.
- name: The name of the item's supplier.
- address1: The street address of the item's supplier.
- address2: The suite number of the item's supplier.
- city: The city of the item's supplier.
- zip: The zip of the item's supplier.
duties: A list of duty objects, each containing information about a duty on the line item.

示例值:

{"fulfillable_quantity":1,"fulfillment_service":"amazon","fulfillment_status":"fulfilled","grams":500,"id":669751112,"price":"199.99","product_id":7513594,"quantity":1,"requires_shipping":true,"sku":"IPOD-342-N","title":"IPod Nano","variant_id":4264112,"variant_title":"Pink","vendor":"Apple","name":"IPod Nano - Pink","gift_card":false,"price_set":{"shop_money":{"amount":"199.99","currency_code":"USD"},"presentment_money":{"amount":"173.30","currency_code":"EUR"}},"properties":[{"name":"custom engraving","value":"Happy Birthday Mom!"}],"taxable":true,"tax_lines":[{"title":"HST","price":"25.81","price_set":{"shop_money":{"amount":"25.81","currency_code":"USD"},"presentment_money":{"amount":"20.15","currency_code":"EUR"}},"channel_liable":true,"rate":0.13}],"total_discount":"5.00","total_discount_set":{"shop_money":{"amount":"5.00","currency_code":"USD"},"presentment_money":{"amount":"4.30","currency_code":"EUR"}},"discount_allocations":[{"amount":"5.00","discount_application_index":2,"amount_set":{"shop_money":{"amount":"5.00","currency_code":"USD"},"presentment_money":{"amount":"3.96","currency_code":"EUR"}}}],"origin_location":{"id":1390592786454,"country_code":"CA","province_code":"ON","name":"Apple","address1":"700 West Georgia Street","address2":"1500","city":"Toronto","zip":"V7Y 1G5"},"duties":[{"id":"2","harmonized_system_code":"520300","country_code_of_origin":"CA","shop_money":{"amount":"164.86","currency_code":"CAD"},"presentment_money":{"amount":"105.31","currency_code":"EUR"},"tax_lines":[{"title":"VAT","price":"16.486","rate":0.1,"price_set":{"shop_money":{"amount":"16.486","currency_code":"CAD"},"presentment_money":{"amount":"10.531","currency_code":"EUR"}},"channel_liable":true}],"admin_graphql_api_id":"gid://shopify/Duty/2"}]}

location_id

string

可选

The ID of the physical location where the order was processed. To determine the locations where the line items are assigned for fulfillment please use the FulfillmentOrder resource.

merchant_of_record_app_id

string

可选

The application acting as Merchant of Record for the order.

name

string

可选

The order name, generated by combining the order_number property with the order prefix and suffix that are set in the merchant's general settings. This is different from the id property, which is the ID of the order used by the API. This field can also be set by the API to be any string value.

note

string

可选

An optional note that a shop owner can attach to the order.

note_attributes

string

可选

Extra information that is added to the order. Appears in the Additional 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"}

number

string

只读可选

The order's position in the shop's count of orders. Numbers are sequential and start at 1.

order_number

string

只读可选

The order 's position in the shop's count of orders starting at 1001. Order numbers are sequential and start at 1001.

original_total_duties_set

string

只读可选

The original total duties charged on the order in shop and presentment currencies.

payment_details

string

已废弃

An object containing information about the payment. It has the following properties:

avs_result_code: The response code from the address verification system (AVS). The code is a single letter. See this chart for the codes and their definitions.
credit_card_bin: The issuer identification number (IIN), formerly known as the bank identification number (BIN), of the customer's credit card. This is made up of the first few digits of the credit card number.
credit_card_company: The name of the company who issued the customer's credit card.
credit_card_number: The customer's credit card number, with most of the leading digits redacted.
cvv_result_code: The response code from the credit card company indicating whether the customer entered the card security code (card verification value) correctly. The code is a single letter or empty string. See this chart for the codes and their definitions.

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 order.
payment_terms_type: The type of selected payment terms template for the 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.

payment_gateway_names

string

只读可选

The list of payment gateways used for the order.

示例值:

authorize_netCash on Delivery (COD)

phone

string

可选

The customer's phone number for receiving SMS notifications.

presentment_currency

string <ISO_4217>

可选

The presentment currency that was used to display prices to the customer.

processed_at

string <ISO_8601>

可选

The date and time (ISO 8601 format)
when an order was processed. This value is the date that appears on your orders and that's used in the
analytic reports. If you're importing
orders from an app or another platform, then you can set processed_at to a date and time
in the past to match when the original order was created.

processing_method

string

只读可选

How the payment was processed. It has the following valid values:

checkout: The order was processed using the Shopify checkout.
direct: The order was processed using a direct payment provider.
manual: The order was processed using a manual payment method.
offsite: The order was processed by an external payment provider to the Shopify checkout.
express: The order was processed using PayPal Express Checkout.
free: The order was processed as a free order using a discount code.

referring_site

string <url>

可选

The website where the customer clicked a link to the shop.

refunds

string

只读可选

A list of refunds applied to the order. For more information, see the Refund API.

示例值:

{"id":18423447608,"order_id":394481795128,"created_at":"2018-03-06T09:35:37-05:00","note":null,"user_id":null,"processed_at":"2018-03-06T09:35:37-05:00","refund_line_items":[],"transactions":[],"order_adjustments":[]}

shipping_address

object (Customer Address)

可选

The mailing address to where the order will be shipped. This address is optional and will not be available on orders that do not require shipping. It 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, town, or village 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 (ISO 3166-1 format) for the country of the shipping address.
first_name: The first name of the person associated with the shipping address.
last_name: The last name of the person associated with the shipping address.
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 region (for example, province, state, or prefecture) of the shipping address.
province_code: The two-letter abbreviation of the region of the shipping address.
zip: The postal code (for example, zip, postcode, or Eircode) of the shipping address.

shipping_lines

string

可选

An array of objects, each of which details a shipping method used. Each object has the following properties:

code: A reference to the shipping method.
discounted_price: The price of the shipping method after line-level discounts have been applied. Doesn't reflect cart-level or order-level discounts.
discounted_price_set: The price of the shipping method in both shop and presentment currencies after line-level discounts have been applied.
price: The price of this shipping method in the shop currency. Can't be negative.
price_set: The price of the shipping method in shop and presentment currencies.
source: The source of the shipping method.
title: The title of the shipping method.
tax_lines: A list of tax line objects, each of which details a tax applicable to this shipping line.
carrier_identifier: A reference to the carrier service that provided the rate. Present when the rate was computed by a third-party carrier service.
requested_fulfillment_service_id: A reference to the fulfillment service that is being requested for the shipping method. Present if the shipping method requires processing by a third party fulfillment service; null otherwise.

示例值:

{"code":"INT.TP","price":"4.00","price_set":{"shop_money":{"amount":"4.00","currency_code":"USD"},"presentment_money":{"amount":"3.17","currency_code":"EUR"}},"discounted_price":"4.00","discounted_price_set":{"shop_money":{"amount":"4.00","currency_code":"USD"},"presentment_money":{"amount":"3.17","currency_code":"EUR"}},"source":"canada_post","title":"Small Packet International Air","tax_lines":[],"carrier_identifier":"third_party_carrier_identifier","requested_fulfillment_service_id":"third_party_fulfillment_service_id"}

source_name

string

可选

The source of the checkout. To use this field for sales attribution, you must register the channels that your app is managing. You can register the channels that your app is managing by completing this Google Form. After you've submited your request, you 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.

source_identifier

string

可选

The ID of the order placed on the originating platform.
This value doesn't correspond to the Shopify ID that's generated from a completed draft.

source_url

string

可选

A valid URL to the original order on the originating surface.
This URL is displayed to merchants on the Order Details page.
If the URL is invalid, then it won't be displayed.

subtotal_price

string

可选

The price of the order in the shop currency after discounts but before shipping, duties, taxes, and tips.

subtotal_price_set

string

可选

The subtotal of the order in shop and presentment currencies after discounts but before shipping, duties, taxes, and tips.

请求参数

示例代码

返回响应

Caution