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.

Order

Multiple access scopes needed — refer to each endpoint for access scope requirements.
Requires access to protected customer data.

An order is a customer's request to purchase one or more products from a shop. You can create, retrieve, update, and delete orders using the Order resource.

Usage notes

  • When you create an order through the API, no payment information is collected, and no transaction is performed.
  • After an order is created, you can change only a few of its attributes using the API. You can't change the items or the quantities in an order using the REST API, but you can change them using the GraphQL Admin API.
  • You can add metafields to the Order resource.
  • You can allow merchants to create orders manually by using the DraftOrder resource.
Caution

You can't use the Order resource to create a new checkout for an individual store. To create a checkout, you need to use the Checkout API or an SDK powered by the Storefront API, such as the JavaScript Buy SDK, iOS Buy SDK, or Android Buy SDK.

Caution

Only the last 60 days' worth of orders from a store are accessible from the Order resource by default. If you want to access older orders, then you need to request access to all orders. If your app is granted access, then you can add the read_all_orders scope to your app along with read_orders or write_orders.

Only use this data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.

Was this section helpful?
#

Endpoints

Anchor to

The Order resource

Anchor to

Properties

app_id
integer
read-only
->
app

The ID of the app that created the order.

billing_address
object
CustomerAddress
->
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. It 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, 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 alphanumeric 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
read-only
->
clientIp

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

buyer_accepts_marketing
boolean
->
customerAcceptsMarketing

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

cancel_reason
string
->
cancelReason

The reason why the order was canceled. Valid values:

Show cancel_reason properties
  • 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
read-only
->
cancelledAt

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

cart_token
string
deprecated

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

checkout_token
string
deprecated

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

client_details
object
read-only
->
customerJourneySummary

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

Show client_details properties
  • 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
boolean
ISO 8601
read-only
->
closedAt

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

company
object
read-only
->
purchasingEntity

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

confirmation_number
string
read-only
->
confirmationNumber

A randomly generated alpha-numeric identifier for the order that may be shown to the customer instead of the sequential order name. This value isn't guaranteed to be unique.

Was this section helpful?
{}

The Order resource

{
"app_id": 1966818,
"billing_address": {
"address1": "2259 Park Ct",
"address2": "Apartment 5",
"city": "Drayton Valley",
"company": null,
"country": "Canada",
"first_name": "Christopher",
"last_name": "Gorski",
"phone": "(555)555-5555",
"province": "Alberta",
"zip": "T0E 0M0",
"name": "Christopher Gorski",
"province_code": "AB",
"country_code": "CA",
"latitude": "45.41634",
"longitude": "-75.6868"
},
"browser_ip": "216.191.105.146",
"buyer_accepts_marketing": false,
"cancel_reason": "customer",
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea",
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"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": "2008-01-10T11:00:00-05:00",
"company": {
"id": 182772,

Anchor to POST request, Create an order
post
Create an order

customerCreate
orderCreate
Requires orders access scope.

Creates an order.

By default, product inventory is not claimed when creating an order.

There are additional optional parameters that can be specified in the body of the request when creating an order:

  • inventory_behaviour: The behaviour to use when updating inventory. (default: bypass)
    • bypass: Do not claim inventory.
    • decrement_ignoring_policy: Ignore the product's inventory policy and claim inventory.
    • decrement_obeying_policy: Follow the product's inventory policy and claim inventory, if possible.
  • send_receipt: Whether to send an order confirmation to the customer. (default: false)
Note

If you're working on a private app and order confirmations are still being sent to the customer when send_receipt is set to false, then you need to disable the Storefront API from the private app's page in the Shopify admin.

  • send_fulfillment_receipt: Whether to send a shipping confirmation to the customer. (default: false)
Note

If you are including shipping_address or billing_address, make sure to pass both first_name and last_name. Otherwise both these addresses will be ignored.

Usage notes:
If you're using this endpoint with a trial or Partner development store, then you can create no more than 5 new orders per minute.

Anchor to Parameters of Create an orderParameters

api_version
string
required
Was this section helpful?

Anchor to post-orders-examplesExamples

Create a comprehensive order

Request body
order
Order resource
Show order properties
order.line_items:[{"title":"Big Brown Bear Boots","price":74.99,"grams":"1300","quantity":3,"tax_lines":[{"price":13.5,"rate":0.06,"title":"State tax"}]}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.
order.total_tax:13.5
string
price

The sum of the prices for all tax lines applied to the order in the shop currency, including refunded and removed tax lines.

order.currency:"EUR"
string
ISO 4217
read-only

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

Create a pending order with an existing customer

Request body
order
Order resource
Show order properties
order.line_items:[{"variant_id":447654529,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.
order.customer:{"id":207119551}
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.

order.financial_status:"pending"
string
read-only

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

Show financial_status properties
  • 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.

Create a simple order and fulfill it

Request body
order
Order resource
Show order properties
order.email:"foo@example.com"
string
email
->
email

The customer's email address.

order.fulfillment_status:"fulfilled"
string

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

Show fulfillment_status properties
  • 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.
order.fulfillments:[{"location_id":24826418}]
array

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

order.line_items:[{"variant_id":447654529,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.

Create a simple order with only a product variant ID and no optional parameters

Request body
order
Order resource
Show order properties
order.line_items:[{"variant_id":447654529,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.

Create a simple order without sending an order receipt or a fulfillment receipt

Request body
order
Order resource
Show order properties
order.email:"foo@example.com"
string
email
->
email

The customer's email address.

order.fulfillment_status:"fulfilled"
string

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

Show fulfillment_status properties
  • 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.
order.line_items:[{"variant_id":447654529,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.

Create a simple order, sending an order confirmation and a shipping confirmation to the customer

Request body
order
Order resource
Show order properties
order.email:"foo@example.com"
string
email
->
email

The customer's email address.

order.fulfillment_status:"fulfilled"
string

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

Show fulfillment_status properties
  • 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.
order.line_items:[{"variant_id":457924702,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.

Create an order and apply a discount

Request body
order
Order resource
Show order properties
order.line_items:[{"variant_id":447654529,"quantity":1}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.
order.email:"jane@example.com"
string
email
->
email

The customer's email address.

order.phone:"18885551234"
string
->
phone

The customer's phone number for receiving SMS notifications.

order.billing_address:{"first_name":"John","last_name":"Smith","address1":"123 Fake Street","phone":"555-555-5555","city":"Fakecity","province":"Ontario","country":"Canada","zip":"K2P 1L4"}
object
CustomerAddress
->
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. It 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, 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 alphanumeric abbreviation of the region of the billing address.
  • zip: The postal code (for example, zip, postcode, or Eircode) of the billing address.
order.shipping_address:{"first_name":"Jane","last_name":"Smith","address1":"123 Fake Street","phone":"777-777-7777","city":"Fakecity","province":"Ontario","country":"Canada","zip":"K2P 1L4"}
object
CustomerAddress
->
shippingAddress

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:

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, 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 alphanumeric abbreviation of the region of the shipping address.
  • zip: The postal code (for example, zip, postcode, or Eircode) of the shipping address.
order.financial_status:"paid"
string
read-only

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

Show financial_status properties
  • 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.
order.discount_codes:[{"code":"FAKE30","amount":"9.00","type":"percentage"}]
array
->
discountCode

A list of discounts applied to the order.

Note

When creating an order, only the first Discount Code supplied in this field is applied to the Order.

Each discount object includes the following properties:

Show discount_codes 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. Valid values:
    • fixed_amount: Applies amount as a unit of the store's currency. For example, if amount is 30 and the store's currency is USD, then 30 USD is deducted from the order total when the discount is applied.
    • percentage: Applies a discount of amount as a percentage of the order total.
    • shipping: Applies a free shipping discount on orders that have a shipping rate less than or equal to amount. For example, if amount is 30, then the discount will give the customer free shipping for any shipping rate that is less than or equal to $30.

Create an order with tax lines split across taxable line items

Request body
order
Order resource
Show order properties
order.line_items:[{"title":"Red Leather Coat","price":129.99,"grams":"1700","quantity":1},{"title":"Blue Suede Shoes","price":85.95,"grams":"750","quantity":1,"taxable":false},{"title":"Raspberry Beret","price":19.99,"grams":"320","quantity":2}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.
order.tax_lines:[{"price":10.2,"rate":0.06,"title":"State tax"},{"price":4.25,"rate":0.025,"title":"County tax"}]
array
->
taxLines

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

Show tax_lines properties
  • price: The amount added to the order for this tax in the shop currency after discounts are applied.
  • rate: The rate of tax to be applied.
  • title: The name of the tax.
  • 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.
When creating an order through the API, tax lines can be specified on the order or the line items but not both. Tax lines specified on the order are split across the taxable line items in the created order.
order.total_tax:14.45
string
price

The sum of the prices for all tax lines applied to the order in the shop currency, including refunded and removed tax lines.

Creating an order with tax lines both on line items and on the order fails and returns an error

Request body
order
Order resource
Show order properties
order.line_items:[{"title":"Clicky Keyboard","price":99.99,"grams":"600","quantity":1,"tax_lines":[{"price":1,"rate":0.01,"title":"Keyboard tax"}]}]
array

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

Show line_items properties
  • attributed_staffs: The staff members attributed to the line item.
    • id: The id of the staff member.
    • quantity: The quantity of the line item attributed to the staff member.
  • 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 handle of a fulfillment service that stocks the product variant belonging to a line item.

    This is the handle of a third-party fulfillment service in the following scenarios:

    Scenario 1

    1. The product variant is stocked by a single fulfillment service.
    2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    Scenario 2

    1. Multiple fulfillment services stock the product variant.
    2. The last time that the line item was unfulfilled, it was awaiting fulfillment by a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.

    If none of the above conditions are met, then this is manual.

    The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

    If you previously set this field, then we recommend that you instead connect inventory items to locations. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

    If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

    Altering the locations which stock a product variant won't change the value of this field for existing orders.

    Learn more about managing inventory quantities and states.

  • 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.
  • current_quantity: The line item's quantity, minus the removed quantity.
  • 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 after discounts are applied.
    • price_set: The amount added to the order for this tax in shop and presentment currencies after discounts are applied.
    • 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 alphanumeric 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.
order.tax_lines:[{"price":6,"rate":0.06,"title":"State tax"}]
array
->
taxLines

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

Show tax_lines properties
  • price: The amount added to the order for this tax in the shop currency after discounts are applied.
  • rate: The rate of tax to be applied.
  • title: The name of the tax.
  • 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.
When creating an order through the API, tax lines can be specified on the order or the line items but not both. Tax lines specified on the order are split across the taxable line items in the created order.
Was this section helpful?
post

/admin/api/2026-04/orders.json

curl -d '{"order":{"line_items":[{"title":"Big Brown Bear Boots","price":74.99,"grams":"1300","quantity":3,"tax_lines":[{"price":13.5,"rate":0.06,"title":"State tax"}]}],"transactions":[{"kind":"sale","status":"success","amount":238.47}],"total_tax":13.5,"currency":"EUR"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-04/orders.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 201 Created
{
"order": {
"id": 1073459979,
"admin_graphql_api_id": "gid://shopify/Order/1073459979",
"app_id": 755357713,
"browser_ip": null,
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": null,
"checkout_id": null,
"checkout_token": null,
"client_details": null,
"closed_at": null,
"confirmation_number": "HQEJEM09X",
"confirmed": true,
"contact_email": null,
"created_at": "2026-01-09T16:39:12-05:00",
"currency": "EUR",
"current_subtotal_price": "224.97",
"current_subtotal_price_set": {
"shop_money": {
"amount": "224.97",
"currency_code": "EUR"
},
"presentment_money": {
"amount": "224.97",
"currency_code": "EUR"
}
},
"current_total_additional_fees_set": null,
"current_total_discounts": "0.00",
"current_total_discounts_set": {
"shop_money": {
"amount": "0.00",

Anchor to POST request, Cancel an order
post
Cancel an order

orderCancel
Requires ANY of the following access scopes: buyer_membership_orders, orders, marketplace_orders.
Caution

For multi-currency orders, the currency property is required whenever the amount property is provided. For more information, refer to the Transaction resource.

Cancels an order. Orders that are paid and have fulfillments can't be canceled.

Anchor to Parameters of Cancel an orderParameters

api_version
string
required
order_id
string
required
amount
string

The amount to refund. If set, Shopify attempts to refund the specified amount, depending on its status. Shopify refunds through a manual gateway in cases where the original transaction was not made in Shopify. Refunds through a manual gateway are recorded as a refund on Shopify, but the customer is not refunded.

currency

The currency of the refund that's issued when the order is canceled. Required for multi-currency orders whenever the amount property is provided.

email
boolean
default false

Whether to send an email to the customer notifying them of the cancellation.

reason
string
default other

The reason for the order cancellation. Valid values: customer, inventory, fraud, declined, and other.)

refund
refund

The refund transactions to perform. Required for some more complex refund situations. For more information, see the Refund API.

restock
boolean
ISO 4217
deprecated
default false

Whether to restock refunded items back to your store's inventory.

Was this section helpful?

Anchor to post-orders-order-id-cancel-examplesExamples

Cancel an order

Path parameters
order_id=450789469
string
required

Cancel and refund an order using the amount property

Path parameters
order_id=450789469
string
required
Request body
amount
Amount resource
Show amount properties
amount:"10.00"
string

The amount to refund. If set, Shopify attempts to refund the specified amount, depending on its status. Shopify refunds through a manual gateway in cases where the original transaction was not made in Shopify. Refunds through a manual gateway are recorded as a refund on Shopify, but the customer is not refunded.

currency:"USD"

The currency of the refund that's issued when the order is canceled. Required for multi-currency orders whenever the amount property is provided.

Cancel and refund an order using the refund property

Path parameters
order_id=450789469
string
required
Request body
refund
Refund resource
Show refund properties
refund:{"note":"Customer made a mistake","shipping":{"full_refund":true},"refund_line_items":[{"line_item_id":466157049,"quantity":1,"restock_type":"cancel","location_id":24826418}],"transactions":[{"parent_id":1068278499,"amount":"10.00","kind":"refund","gateway":"bogus"},{"parent_id":1068278500,"amount":"100.00","kind":"refund","gateway":"gift_card"}]}
refund

The refund transactions to perform. Required for some more complex refund situations. For more information, see the Refund API.

When an order has multiple refundable transactions, refunding an amount less than its net payment without a refund property fails with an error

Path parameters
order_id=450789469
string
required
Request body
amount
Amount resource
Show amount properties
amount:"109.00"
string

The amount to refund. If set, Shopify attempts to refund the specified amount, depending on its status. Shopify refunds through a manual gateway in cases where the original transaction was not made in Shopify. Refunds through a manual gateway are recorded as a refund on Shopify, but the customer is not refunded.

currency:"USD"

The currency of the refund that's issued when the order is canceled. Required for multi-currency orders whenever the amount property is provided.

Was this section helpful?
post

/admin/api/2026-04/orders/450789469/cancel.json

curl -d '{}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-04/orders/450789469/cancel.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 200 OK
{
"order": {
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": "other",
"cancelled_at": "2026-01-09T16:38:58-05:00",
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": null,
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",
"currency_code": "USD"

Anchor to POST request, Close an order
post
Close an order

orderClose
Requires orders access scope.

Closes an order. A closed order is one that has no more work to be done. All items have been fulfilled or refunded.

Anchor to Parameters of Close an orderParameters

api_version
string
required
order_id
string
required
Was this section helpful?

Anchor to post-orders-order-id-close-examplesExamples

Close an order

Path parameters
order_id=450789469
string
required
Was this section helpful?
post

/admin/api/2026-04/orders/450789469/close.json

curl -d '{}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-04/orders/450789469/close.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 200 OK
{
"order": {
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": "2026-01-09T16:39:28-05:00",
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",
"currency_code": "USD"

Anchor to POST request, Re-open a closed order
post
Re-open a closed order

orderOpen
Requires orders access scope.

Re-opens a closed order

Anchor to Parameters of Re-open a closed orderParameters

api_version
string
required
order_id
string
required
Was this section helpful?

Anchor to post-orders-order-id-open-examplesExamples

Re-open a closed order

Path parameters
order_id=450789469
string
required
Was this section helpful?
post

/admin/api/2026-04/orders/450789469/open.json

curl -d '{}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-04/orders/450789469/open.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 200 OK
{
"order": {
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": null,
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",
"currency_code": "USD"

Anchor to GET request, Retrieve a list of orders
get
Retrieve a list of orders

orders
Requires ANY of the following access scopes: orders, marketplace_orders.

Retrieves a list of orders that meet the specified criteria. 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 Retrieve a list of ordersParameters

api_version
string
required
attribution_app_id
string

Show orders attributed to a certain app, specified by the app ID. Set as current to show orders for the app currently consuming the API.

created_at_max
date
ISO 8601

Show orders created at or before date.

created_at_min
date
ISO 8601

Show orders created at or after date.

fields
string

Retrieve only certain fields, specified by a comma-separated list of fields names.

financial_status
string
default any

Filter orders by their financial status.

Show financial_status properties

  • authorized: Show only authorized orders

  • pending: Show only pending orders

  • paid: Show only paid orders

  • partially_paid: Show only partially paid orders

  • refunded: Show only refunded orders

  • voided: Show only voided orders

  • partially_refunded: Show only partially refunded orders

  • any: Show orders of any financial status.

  • unpaid: Show authorized and partially paid orders.

fulfillment_status
string
default any

Filter orders by their fulfillment status.

Show fulfillment_status properties

  • shipped: Show orders that have been shipped. Returns orders with fulfillment_status of fulfilled.

  • partial: Show partially shipped orders.

  • unshipped: Show orders that have not yet been shipped. Returns orders with fulfillment_status of null.

  • any: Show orders of any fulfillment status.

  • unfulfilled: Returns orders with fulfillment_status of null or partial.

ids
string

Retrieve only orders specified by a comma-separated list of order IDs.

limit
integer
int32
≤ 250
default 50

The maximum number of results to show on a page.

name
string

Filter orders by name.

processed_at_max
date
ISO 8601

Show orders imported at or before date.

processed_at_min
date
ISO 8601

Show orders imported at or after date.

Anchor to Response of Retrieve a list of ordersResponse

Returns an array of Order objects
Was this section helpful?

Anchor to get-orders?status=any-examplesExamples

Retrieve all orders

Query parameters
status=any
enum
default open

Filter orders by their status.

Show status properties

  • open: Show only open orders.

  • closed: Show only closed orders.

  • cancelled: Show only canceled orders.

  • any: Show orders of any status, including archived orders.

Retrieve all orders after the specified ID

Query parameters
since_id=123
integer
ISO 8601

Show orders after the specified ID.

Retrieve all orders but show only certain properties

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

Retrieve only certain fields, specified by a comma-separated list of fields names.

Retrieve 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
date
ISO 8601

Show orders last updated at or after date.

Retrieve orders that have authorized payments ready to be captured

Query parameters
financial_status=authorized
string
default any

Filter orders by their financial status.

Show financial_status properties

  • authorized: Show only authorized orders

  • pending: Show only pending orders

  • paid: Show only paid orders

  • partially_paid: Show only partially paid orders

  • refunded: Show only refunded orders

  • voided: Show only voided orders

  • partially_refunded: Show only partially refunded orders

  • any: Show orders of any financial status.

  • unpaid: Show authorized and partially paid orders.

Retrieve specific orders

Query parameters
ids=1073459964
string

Retrieve only orders specified by a comma-separated list of order IDs.

Was this section helpful?
get

/admin/api/2026-04/orders.json?status=any

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-04/orders.json?status=any" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"orders": [
{
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": null,
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",

Anchor to GET request, Retrieve a specific order
get
Retrieve a specific order

order
Requires ANY of the following access scopes: orders, marketplace_orders.

Retrieve an order by specifying the ID. All fields of an order are returned unless specific fields are named. The GET orders endpoint returns open orders by default.

Anchor to Parameters of Retrieve a specific orderParameters

api_version
string
required
order_id
string
required
fields
string

Retrieve only certain fields, specified by a comma-separated list of fields names.

Was this section helpful?

Anchor to get-orders-order-id?fields=id,line-items,name,total-price-examplesExamples

Get only particular fields

Query parameters
fields=id,line_items,name,total_price
string

Retrieve only certain fields, specified by a comma-separated list of fields names.

Retrieve a single order

Was this section helpful?
get

/admin/api/2026-04/orders/450789469.json?fields=id,line_items,name,total_price

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-04/orders/450789469.json?fields=id%2Cline_items%2Cname%2Ctotal_price" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

JSON
HTTP/1.1 200 OK
{
"order": {
"id": 450789469,
"name": "#1001",
"total_price": "598.94",
"line_items": [
{
"id": 466157049,
"admin_graphql_api_id": "gid://shopify/LineItem/466157049",
"current_quantity": 0,
"fulfillable_quantity": 0,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 200,
"name": "IPod Nano - 8gb - green",
"price": "199.00",
"price_set": {
"shop_money": {
"amount": "199.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "199.00",
"currency_code": "USD"
}
},
"product_exists": true,
"product_id": 632910392,
"properties": [
{
"name": "Custom Engraving Front",
"value": "Happy Birthday"
},
{

Anchor to GET request, Retrieve an order count
get
Retrieve an order count

ordersCount
Requires orders access scope.

Retrieve the total number of orders that meet the specified criteria.

Anchor to Parameters of Retrieve an order countParameters

api_version
string
required
created_at_max
date
ISO 8601

Orders created before date specified.

created_at_min
date
ISO 8601

Orders created after date specified.

financial_status
string
default any

Orders of a given financial status.

Show financial_status properties

  • authorized: Authorized orders.

  • pending: Pending orders.

  • paid: Paid orders.

  • partially_paid: Partially paid orders.

  • refunded: Refunded orders.

  • voided: Voided orders.

  • partially_refunded: Partially refunded orders.

  • any: Orders of any financial status.

  • unpaid: Authorized and partially paid orders.

fulfillment_status
string
default any

Orders of a given fulfillment status.

Show fulfillment_status properties

  • shipped: Orders that have been shipped. Returns orders with fulfillment_status of fulfilled.

  • partial: Partially shipped orders.

  • unshipped: Orders that have not yet been shipped. Returns orders with fulfillment_status of null.

  • any: Orders of any fulfillment status.

  • unfulfilled: Orders with fulfillment_status of null or partial.

status
string
default open

Orders of a given status.

Show status properties

  • open: Open orders.

  • closed: Closed orders.

  • any: Orders of any status.

updated_at_max
date
ISO 8601

Orders last updated before date specified.

updated_at_min
date
ISO 8601

Orders last updated after date specified.

Was this section helpful?

Anchor to get-orders-count?status=any-examplesExamples

Count all orders

Query parameters
status=any
string
default open

Orders of a given status.

Show status properties

  • open: Open orders.

  • closed: Closed orders.

  • any: Orders of any status.

Count orders that have authorized payments ready to be captured

Query parameters
financial_status=authorized
string
default any

Orders of a given financial status.

Show financial_status properties

  • authorized: Authorized orders.

  • pending: Pending orders.

  • paid: Paid orders.

  • partially_paid: Partially paid orders.

  • refunded: Refunded orders.

  • voided: Voided orders.

  • partially_refunded: Partially refunded orders.

  • any: Orders of any financial status.

  • unpaid: Authorized and partially paid orders.

Was this section helpful?
get

/admin/api/2026-04/orders/count.json?status=any

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-04/orders/count.json?status=any" \
-H "X-Shopify-Access-Token: {access_token}"
{}

Response

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

Anchor to PUT request, Update an order
put
Update an order

orderUpdate
Requires ANY of the following access scopes: orders, marketplace_orders.

This operation allows for updating properties of an order including buyer_accepts_marketing, email, phone, note, tags, metafields and shipping_address_attributes.

It is not for editing the items of an order.

Note

After an order is created, you can change only a few of its attributes using the API. You can't change the items or the quantities in an order using the REST API, but you can change them using the GraphQL Admin API.

Anchor to Parameters of Update an orderParameters

api_version
string
required
order_id
string
required
Was this section helpful?

Anchor to put-orders-order-id-examplesExamples

Add a metafield to an order

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

Add a note to order

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

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

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

Add note attributes to an order

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.note_attributes:[{"name":"colour","value":"red"}]
array
->
customAttributes

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.

Change an order's email address

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.email:"a-different@email.com"
string
email
->
email

The customer's email address.

Change an order's phone number

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.phone:"+15145556677"
string

The customer's phone number for receiving SMS notifications.

Change whether the customer accepts marketing

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.buyer_accepts_marketing:true
boolean

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

Remove the customer from an order

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.customer:null
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.

Update an order's tags

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.tags:"External, Inbound, Outbound"
string
->
tags

Tags attached to the order, formatted as a string of comma-separated values. Tags are additional short descriptors, commonly used for filtering and searching. Each individual tag is limited to 40 characters in length.

Update the shipping address of an order

Path parameters
order_id=450789469
string
required
Request body
order
Order resource
Show order properties
order.id:450789469
integer
read-only

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.'

order.shipping_address:{"address1":"123 Ship Street","city":"Shipsville"}
object
CustomerAddress
->
shippingAddress

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:

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, 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 alphanumeric abbreviation of the region of the shipping address.
  • zip: The postal code (for example, zip, postcode, or Eircode) of the shipping address.
Was this section helpful?
put

/admin/api/2026-04/orders/450789469.json

curl -d '{"order":{"id":450789469,"metafields":[{"key":"new","value":"newvalue","type":"single_line_text_field","namespace":"global"}]}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2026-04/orders/450789469.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}

Response

JSON
HTTP/1.1 200 OK
{
"order": {
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": null,
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",
"currency_code": "USD"

Anchor to DELETE request, Delete an order
del
Delete an order

orderDelete
Requires orders access scope.

Deletes an order. Orders that interact with an online gateway can't be deleted.

Anchor to Parameters of Delete an orderParameters

api_version
string
required
order_id
string
required
Was this section helpful?

Anchor to delete-orders-order-id-examplesExamples

Delete an order

Path parameters
order_id=450789469
string
required
Was this section helpful?
del

/admin/api/2026-04/orders/450789469.json

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

Response

JSON
HTTP/1.1 200 OK
{}