Get Order

Gets an Order. To learn more about creating or updating orders, see Orders Overview.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Orders	modify	`store_v2_orders`
Orders	read-only	`store_v2_orders_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

order_idstringRequired

Query parameters

includelist of enumsOptional

consignments - include the response returned from the request to the /orders/{order_id}/consignments endpoint. Current default array structure is legacy and will be deprecated from 1 Feb 2026. Specify consignment_structure=object as a request parameter when including consignments.
consignments.line_items - include the response returned from the request to the /orders/{order_id}/products endpoint in consignments. This will also includes the resources associated with include=consignments. Current default array structure is legacy and will be deprecated from 1 Feb 2026. Specify consignment_structure=object as a request parameter when including consignments.
fees - include the response returned from the request to the /orders/{order_id}/fees endpoint.

* `consignments` - include the response returned from the request to the `/orders/{order_id}/consignments` endpoint. Current default array structure is legacy and will be deprecated from **1 Feb 2026**. Specify `consignment_structure=object` as a request parameter when including consignments. * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. This will also includes the resources associated with `include=consignments`. Current default array structure is legacy and will be deprecated from **1 Feb 2026**. Specify `consignment_structure=object` as a request parameter when including consignments. * `fees` - include the response returned from the request to the `/orders/{order_id}/fees` endpoint.

Allowed values:

consignment_structureenumOptional

Should be specified along with include=consignments or include=consignments.line_items to return consignments in the supported object structure. The default array structure provided is legacy and may not be supported in the future.

Allowed values:

Response

Order Response.

base_handling_coststring

The value of the base handling cost. The value can’t be negative. (Float, Float-As-String, Integer)

base_shipping_coststring

The value of the base shipping cost. The value can’t be negative. (Float, Float-As-String, Integer)

base_wrapping_coststring

The value of the base wrapping cost expressed as a floating point number to four decimal places in string format. The value can't be negative.

billing_addressobject

cart_idstring

The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a read-only field; do not set or modify its value in a POST or PUT request.

channel_idinteger

Shows where the order originated. The channel_id defaults to 1. The value must match the ID of a valid and enabled channel. If the ID refers to a non-existing or disconnected channel, the POST and PUT /v2/orders endpoints return a validation error.

consignmentsobject

coupon_discountstring

A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)

couponsobjectRead-only

currency_codestring

The currency code of the display currency used to present prices to the shopper on the storefront. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request.

currency_exchange_ratestring

The exchange rate between the store’s default currency and the display currency. A read-only value. Do not pass in a POST or PUT request. For orders created using the V2 endpoints, this value is always 1 (only in the storefront this value can be different to 1). (Float, Float-As-String, Integer)

currency_idinteger

The display currency ID. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request. In v2 display currency is set to the transactional currency, ”default_currency_id”.

customer_iddouble

customer_localestring

The customer’s locale. The supported formats are:

2-char lowercase characters. e.g., en
3-char lowercase characters. e.g., asa
5-char the language code is 2 lowercase characters and the region code is 2 uppercase characters, with - in the middle. e.g., en-US
6-char the language code is 2 lowercase character and the region code is three digit number, with - in the middle. e.g., es-419

The customer’s locale. The supported formats are: - 2-char lowercase characters. e.g., `en` - 3-char lowercase characters. e.g., `asa` - 5-char the language code is 2 lowercase characters and the region code is 2 uppercase characters, with `-` in the middle. e.g., `en-US` - 6-char the language code is 2 lowercase character and the region code is three digit number, with `-` in the middle. e.g., `es-419`

customer_messagestring

Message that the customer entered (number, options) -o the Order Comments box during checkout.

date_createdstring

The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., Tue, 20 Nov 2012 00:00:00 +0000. This date time is always in UTC in the api response.

date_modifiedstring

A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822. This date time is always in UTC in the api response.

date_shippedstring

A read-only value representing the date when the order is fully shipped. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822

default_currency_codestring

The currency code of the transactional currency the shopper pays in.

default_currency_idinteger

The transactional currency ID. A read-only value. Do not pass in a POST or PUT request.

discount_amountstring

Amount of discount for this transaction. The value can’t be negative. (Float, Float-As-String, Integer)

ebay_order_idstring

If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.

external_idstring or nullRead-only

(Read-only) The order ID in another system, such as the Amazon order ID if this is an Amazon order.

external_merchant_idstring or null

The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the external_merchant_id. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again.

external_order_idstring

The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you can update this field using a POST or PUT request.

external_sourcestring or null

This value identifies an external system that generated the order and submitted it to BigCommerce with the Orders API.

When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square).
If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing.
If you do not provide a value, then it will default to null.

This value identifies an external system that generated the order and submitted it to BigCommerce with the Orders API. * When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square). * If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing. * If you do not provide a value, then it will default to null.

feesobject or list of objects

geoip_countrystring

The full name of the country where the customer made the purchase, based on the IP.

geoip_country_iso2string

The country where the customer made the purchase, in ISO2 format, based on the IP.

gift_certificate_amountstring

A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)

handling_cost_ex_taxstring

The value of the handling cost, excluding tax. The value can’t be negative. (Float, Float-As-String, Integer)

handling_cost_inc_taxstring

The value of the handling cost, including tax. The value can’t be negative. (Float, Float-As-String, Integer)

handling_cost_taxstring

A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)

handling_cost_tax_class_idinteger

A read-only value. Do not attempt to set or modify this value in a POST or PUT request.

(NOTE: Value ignored if automatic tax is enabled on the store.)

idinteger

Read-only. The ID of the order.

ip_addressstring<=30 characters

IPv4 Address of the customer, if known.

Note: You can set either ip_address or ip_address_v6. Setting the ip_address value will reset the ip_address_v6 value and vice versa.

ip_address_v6string<=39 characters

IPv6 Address of the customer, if known.

Note: You can set either ip_address or ip_address_v6. Setting the ip_address_v6 value will reset the ip_address value and vice versa.

is_deletedboolean

Indicates whether the order is deleted/archived. When set to true in a PUT request, it has the same result as the DELETE an order request.

is_email_opt_inboolean

Indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT.

is_tax_inclusive_pricingboolean

Indicate whether the order’s base prices include tax.

If true, the base prices are inclusive of tax, and the values of subtotal_inc_tax, shipping_cost_inc_tax, handling_cost_inc_tax, wrapping_cost_inc_tax and total_inc_tax are not estimated but actual values and can be reliable for accounting purposes.

If false, the base prices are exclusive of tax, and the values of subtotal_ex_tax, shipping_cost_ex_tax, handling_cost_ex_tax, wrapping_cost_ex_tax and total_ex_tax are not estimated but actual values and can be reliable for accounting purposes.

Indicate whether the order's base prices include tax. If true, the base prices are inclusive of tax, and the values of `subtotal_inc_tax`, `shipping_cost_inc_tax`, `handling_cost_inc_tax`, `wrapping_cost_inc_tax` and `total_inc_tax` are not estimated but actual values and can be reliable for accounting purposes. If false, the base prices are exclusive of tax, and the values of `subtotal_ex_tax`, `shipping_cost_ex_tax`, `handling_cost_ex_tax`, `wrapping_cost_ex_tax` and `total_ex_tax` are not estimated but actual values and can be reliable for accounting purposes.

items_shippeddouble

The number of items that have been shipped.

items_totaldouble

The total number of items in the order.

order_is_digitalboolean

Whether this is an order for digital products.

order_sourcestring

payment_methodstring

The payment method for this order. For example, Manual, Credit Card, cash, Test Payment Gateway, etc.

payment_provider_idstring or double

The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).

payment_statusenum

A read-only value. Do not attempt to set or modify this value in a POST or PUT request.

productsobjectRead-only

refunded_amountstring

The amount refunded from this transaction; always returns 0. The value can’t be negative. (Float, Float-As-String, Integer)

shipping_address_countdouble

The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.

shipping_addressesobjectRead-only

shipping_cost_ex_taxstring

The value of shipping cost, excluding tax. When specified in a POST or PUT request, the field shipping_cost_inc_tax is also required. The value can’t be negative (Float, Float-As-String, Integer)

shipping_cost_inc_taxstring

The value of shipping cost, including tax. When specified in a POST or PUT request, the field shipping_cost_ex_tax is also required. The value can’t be negative. (Float, Float-As-String, Integer)

shipping_cost_taxstring

A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)

shipping_cost_tax_class_idinteger

Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)

staff_notesstring<=65535 characters

Any additional notes for staff.

statusstring

The status will include one of the (string, options) - values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation.

status_idinteger

The status ID of the order.

store_credit_amountstring

Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)

store_default_currency_codestring

The currency code of the storeʼs default currency.

store_default_to_transactional_exchange_ratestring

The exchange rate between the storeʼs default currency and the transactional currency used in the order.

subtotal_ex_taxstring

Override value for subtotal excluding tax. The value can’t be negative. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)

subtotal_inc_taxstring

Override value for subtotal including tax. The value can’t be negative. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)

subtotal_taxstring

A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer)

tax_provider_idstring

Read-only. BasicTaxProvider - Tax is set to manual and order is created in the store.

AvaTaxProvider - Tax is set to automatic and order is created in the store. Used for Avalara.

"" (empty string) - The order is created with the API, or the tax provider is unknown.

total_ex_taxstring

Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. The value can’t be negative. (Float, Float-As-String, Integer)

total_inc_taxstring

Override value for the total, including tax. If specified, the field total_ex_tax is also required. The value can’t be negative. (Float, Float-As-String, Integer)

total_taxstring

Total tax amount for the order

wrapping_cost_ex_taxstring

The value of the wrapping cost, excluding tax. The value can’t be negative. (Float, Float-As-String, Integer)

wrapping_cost_inc_taxstring

The value of the wrapping cost, including tax. The value can’t be negative. (Float, Float-As-String, Integer)

wrapping_cost_taxstring

A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)

wrapping_cost_tax_class_idinteger

A read-only value. Do not attempt to set or modify this value in a POST or PUT request.

NOTE: Value ignored if automatic tax is enabled on the store.

Errors

404

Not Found Error

1	{
2	"base_handling_cost": "0.0000",
3	"base_shipping_cost": "12.0000",
4	"base_wrapping_cost": "0.0000",
5	"billing_address": {
6	"zip": "78108",
7	"city": "Austin",
8	"company": "",
9	"country": "United States",
10	"country_iso2": "US",
11	"email": "janedoe@example.com",
12	"first_name": "Jane",
13	"form_fields": [
14	{
15	"name": "Delivery Instructions",
16	"value": "Leave in backyard"
17	}
18	],
19	"last_name": "Doe",
20	"phone": "1234567890",
21	"state": "Texas",
22	"street_1": "555 East Street",
23	"street_2": ""
24	},
25	"cart_id": "7e48f7ef-2e88-4817-aea4-b0ed01490114",
26	"channel_id": 1,
27	"coupon_discount": "5.0000",
28	"coupons": {
29	"url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/coupons",
30	"resource": "/orders/218/coupons"
31	},
32	"currency_code": "USD",
33	"currency_exchange_rate": "1.0000000000",
34	"currency_id": 1,
35	"customer_id": 11,
36	"customer_locale": "en",
37	"customer_message": "",
38	"date_created": "Tue, 05 Mar 2019 21:40:11 +0000",
39	"date_modified": "Mon, 11 Mar 2019 15:17:25 +0000",
40	"date_shipped": "",
41	"default_currency_code": "USD",
42	"default_currency_id": 1,
43	"discount_amount": "5.0000",
44	"ebay_order_id": "0",
45	"external_order_id": "external-order-id",
46	"fees": [
47	{
48	"id": 1,
49	"type": "custom_fee",
50	"display_name_customer": "A Fee",
51	"display_name_merchant": "A Fee",
52	"source": "AA",
53	"base_cost": "12.3000",
54	"cost_exc_tax": "12.3000",
55	"cost_inc_tax": "12.3000",
56	"cost_tax": "0.0000",
57	"tax_class_id": 22
58	},
59	{
60	"id": 2,
61	"type": "custom_fee",
62	"display_name_customer": "B Fee",
63	"display_name_merchant": "B Fee",
64	"source": "AA",
65	"base_cost": "4.0000",
66	"cost_ex_tax": "4.0000",
67	"cost_inc_tax": "12.0000",
68	"cost_tax": "8.0000"
69	}
70	],
71	"geoip_country": "",
72	"geoip_country_iso2": "",
73	"gift_certificate_amount": "0.0000",
74	"handling_cost_ex_tax": "0.0000",
75	"handling_cost_inc_tax": "0.0000",
76	"handling_cost_tax": "0.0000",
77	"handling_cost_tax_class_id": 0,
78	"id": 218,
79	"ip_address": "",
80	"ip_address_v6": "",
81	"is_email_opt_in": false,
82	"is_tax_inclusive_pricing": false,
83	"items_shipped": 0,
84	"items_total": 4,
85	"order_is_digital": false,
86	"order_source": "external",
87	"payment_method": "Cash",
88	"payment_provider_id": "",
89	"payment_status": "authorized",
90	"products": {
91	"url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/products",
92	"resource": "/orders/218/products"
93	},
94	"refunded_amount": "0.0000",
95	"shipping_address_count": 1,
96	"shipping_addresses": {
97	"url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/shippingaddresses",
98	"resource": "/orders/218/shippingaddresses"
99	},
100	"shipping_cost_ex_tax": "11.0900",
101	"shipping_cost_inc_tax": "12.0000",
102	"shipping_cost_tax": "0.9100",
103	"shipping_cost_tax_class_id": 0,
104	"staff_notes": "",
105	"status": "Awaiting Payment",
106	"status_id": 7,
107	"store_credit_amount": "0.0000",
108	"store_default_currency_code": "",
109	"store_default_to_transactional_exchange_rate": "1.0000000000",
110	"subtotal_ex_tax": "62.6793",
111	"subtotal_inc_tax": "67.8400",
112	"subtotal_tax": "4.4000",
113	"tax_provider_id": "BasicTaxProvider",
114	"total_ex_tax": "64.5300",
115	"total_inc_tax": "69.8400",
116	"total_tax": "5.3100",
117	"wrapping_cost_ex_tax": "0.0000",
118	"wrapping_cost_inc_tax": "0.0000",
119	"wrapping_cost_tax": "0.0000",
120	"wrapping_cost_tax_class_id": 0,
121	"custom_status": "Awaiting Payment"
122	}

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Query parameters

Response

Errors

OAuth scopes

Authentication header

Further reading

1	curl https://api.bigcommerce.com/stores/store_hash/v2/orders/order_id \
2	-H "X-Auth-Token: <apiKey>"