Orders | BigCommerce Dev Center

Orders V2

Manage order coupons, messages, products, shipping addresses, statuses, taxes, shipments, and shipping address quotes.

Order

The Order object contains a record of the purchase agreement between a shopper and a merchant. To learn more about creating orders, see Orders API Guide.

Currency Fields

The default currency refers to the transactional currency which is the currency the shopper pays in.

The display currency refers to the presentational currency used to present prices to the shopper on the storefront.

currency_id - the display currency ID. Depending on the currency selected, the value may be different from the transactional currency.
currency_code - the currency code of the display currency used to present prices to the shopper on the storefront. Depending on the currency selected, the value may be different from the transactional currency.
currency_exchange_rate - the exchange rate between the store’s default currency and the display currency. For orders created using the V2 endpoints, this value is always 1 (only in the storefront this value can be different to 1).
default_currency_id - the transactional currency ID.
default_currency_code - the currency code of the transactional currency the shopper pays in.

The following additional fields are returned on orders when Multi-Currency is enabled on the store:

store_default_currency_code - the currency code of the store’s default currency.
store_default_to_transactional_exchange_rate - the exchange rate between the store’s default currency and the transactional currency used in the order.

Example:

{
  ...
  "currency_id": 4,
  "currency_code": "EUR",
  "currency_exchange_rate": 1,
  "default_currency_id": 4,
  "default_currency_code": "EUR",
  "store_default_currency_code": "USD",
  "store_default_to_transactional_exchange_rate": "100.0000000000"
  ...
}

Get an Order

GET https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{order_id}

Request

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

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
order_id in path - integer - required
ID of the order.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Order Response.

Body

application/json

Order object returned in responses.

idinteger
Read-only. The ID of the order.
Example: 118
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
date_shippedstring
A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822
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.
Example: a8458391-ef68-4fe5-9ec1-442e6a767364
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.
Example: Awaiting Fulfillment
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)
Example: 0.0000
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 3
payment_statusstring
A read-only value. Do not attempt to set or modify this value in a POST or PUT request.
Allowed: authorized | captured | capture pending | declined | held for review | paid | partially refunded | pending | refunded | void | void pending
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)
Example: 0.0000
gift_certificate_amountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 0.0000
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'.
Example: 1
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.
Example: USD
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)
Example: 1.0000000000
default_currency_idinteger
The transactional currency ID. A read-only value. Do not pass in a POST or PUT request.
Example: 1
default_currency_codestring
The currency code of the transactional currency the shopper pays in.
Example: EUR
store_default_currency_codestring
The currency code of the store's default currency.
Example: USD
store_default_to_transactional_exchange_ratestring
The exchange rate between the store's default currency and the transactional currency used in the order.
Example: 100.0000000000
coupon_discountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 5.0000
shipping_address_countnumber
The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.
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.
Example: false
order_sourcestring
Orders submitted from the store's website will include a www value. Orders submitted with the Checkout API will be set to checkout_api.
Example: www, iPhone, Android, mobile, manual
consignmentsobject
productsobject
shipping_addressesobject
couponsobject
status_idinteger
The status ID of the order.
Example: 7
billing_addressobject

base_handling_coststring
The value of the base handling cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_shipping_coststring
The value of the base shipping cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_wrapping_coststring
The value of the base wrapping cost expressed as a floating point number to four decimal places in string format.
Example: 0.0000
billing_addressobject
channel_idinteger
Shows where the order originated. The channel_id will default to 1.
Example: 1
customer_idnumber
customer_messagestring
Message that the customer entered (number, options) -o the Order Comments box during checkout.
Example: Thank you
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.
default_currency_codestring
The currency code of the transactional currency the shopper pays in; writeable when multi-currency is enabled.
discount_amountstring
Amount of discount for this transaction. (Float, Float-As-String, Integer)
Example: 0.0000
ebay_order_idstring
If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
Example: 0
external_id
The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the external_id. You can update this field using 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.
One of:
Type: string
Example: null
external_merchant_id
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.
One of:
Type: string
Example: null
external_sourcestring
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.
Example: null
geoip_countrystring
The full name of the country where the customer made the purchase, based on the IP.
Example: United States
geoip_country_iso2string
The country where the customer made the purchase, in ISO2 format, based on the IP.
Example: US
handling_cost_ex_taxstring
The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
handling_cost_inc_taxstring
The value of the handling cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
ip_addressstring
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.
<= 30 characters
Example: 12.345.678.910
ip_address_v6string
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.
<= 39 characters
Example: 2001:db8:3333:4444:5555:6666:7777:8888
is_deletedboolean
Indicates whether the order was deleted (archived). Set to to true, to archive an order.
Example: false
items_shippednumber
The number of items that have been shipped.
Example: 0
items_totalnumber
The total number of items in the order.
Example: 1
order_is_digitalboolean
Whether this is an order for digital products.
Example: false
payment_methodstring
The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.
Allowed: Credit Card | Cash | Test Payment Gateway | Manual
payment_provider_id
The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
One of:
Type: string
Example:
refunded_amountstring
The amount refunded from this transaction; always returns 0. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_ex_taxstring
The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_inc_taxstring
The value of shipping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
staff_notesstring
Any additional notes for staff.
<= 65535 characters
Example: Send Saturday
status_idinteger
The status ID of the order.
subtotal_ex_taxstring
Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
subtotal_inc_taxstring
Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
tax_provider_idstring
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.
Allowed: BasicTaxProvider | AvaTaxProvider |
customer_localestring
The customer’s locale.
Example: en
external_order_idstring
The external id of the order.
Example: external-order-id
total_ex_taxstring
Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
total_inc_taxstring
Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
wrapping_cost_ex_taxstring
The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
wrapping_cost_inc_taxstring
The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000

response

{
  "id": 218,
  "customer_id": 11,
  "date_created": "Tue, 05 Mar 2019 21:40:11 +0000",
  "date_modified": "Mon, 11 Mar 2019 15:17:25 +0000",
  "date_shipped": "",
  "status_id": 7,
  "status": "Awaiting Payment",
  "subtotal_ex_tax": "62.6793",
  "subtotal_inc_tax": "67.8400",
  "subtotal_tax": "4.4000",
  "base_shipping_cost": "12.0000",
  "shipping_cost_ex_tax": "11.0900",
  "shipping_cost_inc_tax": "12.0000",
  "shipping_cost_tax": "0.9100",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "64.5300",
  "total_inc_tax": "69.8400",
  "total_tax": "5.3100",
  "items_total": 4,
  "items_shipped": 0,
  "payment_method": "Cash",
  "payment_provider_id": "",
  "payment_status": "authorized",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "ip_address_v6": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": "5.0000",
  "coupon_discount": "5.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": "0",
  "cart_id": "7e48f7ef-2e88-4817-aea4-b0ed01490114",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": 78108,
    "country": "United States",
    "country_iso2": "US",
    "phone": 1234567890,
    "email": "janedoe@example.com",
    "form_fields": [
      {
        "name": "Delivery Instructions",
        "value": "Leave in backyard"
      }
    ]
  },
  "is_email_opt_in": false,
  "credit_card_type": null,
  "order_source": "external",
  "channel_id": 1,
  "external_source": null,
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/products",
    "resource": "/orders/218/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/shippingaddresses",
    "resource": "/orders/218/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/coupons",
    "resource": "/orders/218/coupons"
  },
  "external_id": null,
  "external_merchant_id": null,
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "",
  "store_default_to_transactional_exchange_rate": "1.0000000000",
  "custom_status": "Awaiting Payment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Multiple Items

{
  "id": 247,
  "customer_id": 11,
  "date_created": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_modified": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_shipped": "",
  "status_id": 11,
  "status": "Awaiting Fulfillment",
  "subtotal_ex_tax": 924.47,
  "subtotal_inc_tax": 1000.74,
  "subtotal_tax": 76.27,
  "base_shipping_cost": 8,
  "shipping_cost_ex_tax": 7.39,
  "shipping_cost_inc_tax": 8,
  "shipping_cost_tax": 0.61,
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": 0,
  "handling_cost_ex_tax": 0,
  "handling_cost_inc_tax": 0,
  "handling_cost_tax": 0,
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": 0,
  "wrapping_cost_ex_tax": 0,
  "wrapping_cost_inc_tax": 0,
  "wrapping_cost_tax": 0,
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": 931.86,
  "total_inc_tax": 1008.74,
  "total_tax": 76.88,
  "items_total": 11,
  "items_shipped": 0,
  "payment_method": "Test Payment Gateway",
  "payment_provider_id": "",
  "payment_status": "captured",
  "refunded_amount": 0,
  "order_is_digital": false,
  "store_credit_amount": 0,
  "gift_certificate_amount": 0,
  "ip_address": "70.112.53.67",
  "geoip_country": "United States",
  "geoip_country_iso2": "US",
  "currency_id": 1,
  "currency_code\"": "USD",
  "currency_exchange_rate": 1,
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "BIN-45",
  "customer_message": "Custom Journal Added",
  "discount_amount": 0,
  "coupon_discount\"": 0,
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": 0,
  "cart_id": "8b84f622-faf1-4c10-887b-f5dff2f9eaf4",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78108",
    "country": "United States",
    "country_iso2": "US",
    "phone": "1234567890",
    "email": "janedoe@email.com",
    "form_fields": {
      "name": "Delivery Instructions",
      "value": "Leave in backyard"
    }
  },
  "is_email_opt_in": false,
  "credit_card_type": {},
  "order_source": "manual",
  "channel_id": 1,
  "external_source": {},
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/products",
    "resource": "/orders/247/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/shippingaddresses",
    "resource": "/orders/247/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/coupons",
    "resource": "/orders/247/coupons"
  },
  "external_id": {},
  "external_merchant_id": {},
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "USD",
  "store_default_to_transactional_exchange_rate": 1,
  "custom_status": "Awaiting Fulfillment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Update an Order

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{order_id}

Request

Updates an Order.

To add a product to an existing order, don't include id in the body. Include product_options if adding a product with variants.

To update a product in an order, include id in the body. The body should only contain the fields that need to be updated. Those fields that are omitted will not be changed.

To remove a product from an order, set that product’s quantity to 0.

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

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

application/json

base_handling_coststring
The value of the base handling cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_shipping_coststring
The value of the base shipping cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_wrapping_coststring
The value of the base wrapping cost expressed as a floating point number to four decimal places in string format.
Example: 0.0000
billing_address
channel_idinteger
Shows where the order originated. The channel_id will default to 1.
Example: 1
consignmentsobject
customer_idnumber
customer_messagestring
Message that the customer entered (number, options) -o the Order Comments box during checkout.
Example: Thank you
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.
default_currency_codestring
A read-only field displays the currency code of the transactional currency the shopper uses.
discount_amountstring
Amount of discount for this transaction. (Float, Float-As-String, Integer)
Example: 0.0000
ebay_order_idstring
If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
Example: 0
external_id
The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the external_id. You can update this field using 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.
One of:
Type: string
Example: null
external_merchant_id
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.
One of:
Type: string
Example: null
external_sourcestring
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.
Example: null
geoip_countrystring
The full name of the country where the customer made the purchase, based on the IP.
Example: United States
geoip_country_iso2string
The country where the customer made the purchase, in ISO2 format, based on the IP.
Example: US
handling_cost_ex_taxstring
The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
handling_cost_inc_taxstring
The value of the handling cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
ip_addressstring
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.
<= 30 characters
Example: 12.345.678.910
ip_address_v6string
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.
<= 39 characters
Example: 2001:db8:3333:4444:5555:6666:7777:8888
is_deletedboolean
Indicates whether the order was deleted (archived). Set to to true, to archive an order.
Example: false
items_shippednumber
The number of items that have been shipped.
Example: 0
items_totalnumber
The total number of items in the order.
Example: 1
order_is_digitalboolean
Whether this is an order for digital products.
Example: false
payment_methodstring
The payment method for this order. Can be one of the following: Manual, Credit Card, Cash,Test Payment Gateway, etc.
payment_provider_id
The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
One of:
Type: string
Example:
productsarray[]
refunded_amountstring
The amount refunded from this transaction; always returns 0. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_ex_taxstring
The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_inc_taxstring
The value of shipping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
staff_notesstring
Any additional notes for staff.
<= 65535 characters
Example: Send Saturday
shipping_addresses
status_idinteger
The status ID of the order.
subtotal_ex_taxstring
Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
subtotal_inc_taxstring
Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
tax_provider_idstring
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.
Allowed: BasicTaxProvider | AvaTaxProvider |
customer_localestring
The customer’s locale.
Example: en
external_order_idstring
The external id of the order.
Example: external-order-id
total_ex_taxstring
Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
total_inc_taxstring
Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
wrapping_cost_ex_taxstring
The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
wrapping_cost_inc_taxstring
The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000

application/json

{
  "status_id": 0,
  "customer_id": 11,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@example.com"
  },
  "shipping_addresses": [
    {
      "first_name": "Trish",
      "last_name": "Test",
      "company": "Acme Pty Ltd",
      "street_1": "666 Sussex St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "email": "elsie@example.com"
    }
  ],
  "products": [
    {
      "name": "BigCommerce Poster",
      "quantity": 1,
      "price_inc_tax": 10.98,
      "price_ex_tax": 10
    },
    {
      "name": "BigCommerce Coffee Mug",
      "quantity": 1,
      "price_inc_tax": 50,
      "price_ex_tax": 45
    },
    {
      "product_id": 184,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "192"
        }
      ]
    }
  ],
  "customer_locale": "en"
}

Adding an existing product to order

{
  "products": [
    {
      "product_id": 123,
      "quantity": 5,
      "product_options": {
        "id": 56,
        "value": 12
      },
      "price_inc_tax": 12.45,
      "price_ex_tax": 10.12
    }
  ]
}

Adding a new product to order

{
  "products": [
    {
      "name": "BigCommerce Coffee Mug",
      "quantity": 1,
      "price_inc_tax": 12.45,
      "price_ex_tax": 10.12,
      "sku": "MUG-GRY"
    }
  ]
}

Removing a product from an order

{
  "products": [
    {
      "product_id": 123,
      "quantity": 0,
      "product_options": {
        "id": 56,
        "value": 12
      },
      "price_inc_tax": 12.45,
      "price_ex_tax": 10.12
    }
  ]
}

Response

Order Response.

Body

application/json

Order object returned in responses.

idinteger
Read-only. The ID of the order.
Example: 118
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
date_shippedstring
A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822
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.
Example: a8458391-ef68-4fe5-9ec1-442e6a767364
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.
Example: Awaiting Fulfillment
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)
Example: 0.0000
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 3
payment_statusstring
A read-only value. Do not attempt to set or modify this value in a POST or PUT request.
Allowed: authorized | captured | capture pending | declined | held for review | paid | partially refunded | pending | refunded | void | void pending
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)
Example: 0.0000
gift_certificate_amountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 0.0000
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'.
Example: 1
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.
Example: USD
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)
Example: 1.0000000000
default_currency_idinteger
The transactional currency ID. A read-only value. Do not pass in a POST or PUT request.
Example: 1
default_currency_codestring
The currency code of the transactional currency the shopper pays in.
Example: EUR
store_default_currency_codestring
The currency code of the store's default currency.
Example: USD
store_default_to_transactional_exchange_ratestring
The exchange rate between the store's default currency and the transactional currency used in the order.
Example: 100.0000000000
coupon_discountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 5.0000
shipping_address_countnumber
The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.
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.
Example: false
order_sourcestring
Orders submitted from the store's website will include a www value. Orders submitted with the Checkout API will be set to checkout_api.
Example: www, iPhone, Android, mobile, manual
consignmentsobject
productsobject
shipping_addressesobject
couponsobject
status_idinteger
The status ID of the order.
Example: 7
billing_addressobject

base_handling_coststring
The value of the base handling cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_shipping_coststring
The value of the base shipping cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_wrapping_coststring
The value of the base wrapping cost expressed as a floating point number to four decimal places in string format.
Example: 0.0000
billing_addressobject
channel_idinteger
Shows where the order originated. The channel_id will default to 1.
Example: 1
customer_idnumber
customer_messagestring
Message that the customer entered (number, options) -o the Order Comments box during checkout.
Example: Thank you
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.
default_currency_codestring
The currency code of the transactional currency the shopper pays in; writeable when multi-currency is enabled.
discount_amountstring
Amount of discount for this transaction. (Float, Float-As-String, Integer)
Example: 0.0000
ebay_order_idstring
If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
Example: 0
external_id
The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the external_id. You can update this field using 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.
One of:
Type: string
Example: null
external_merchant_id
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.
One of:
Type: string
Example: null
external_sourcestring
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.
Example: null
geoip_countrystring
The full name of the country where the customer made the purchase, based on the IP.
Example: United States
geoip_country_iso2string
The country where the customer made the purchase, in ISO2 format, based on the IP.
Example: US
handling_cost_ex_taxstring
The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
handling_cost_inc_taxstring
The value of the handling cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
ip_addressstring
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.
<= 30 characters
Example: 12.345.678.910
ip_address_v6string
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.
<= 39 characters
Example: 2001:db8:3333:4444:5555:6666:7777:8888
is_deletedboolean
Indicates whether the order was deleted (archived). Set to to true, to archive an order.
Example: false
items_shippednumber
The number of items that have been shipped.
Example: 0
items_totalnumber
The total number of items in the order.
Example: 1
order_is_digitalboolean
Whether this is an order for digital products.
Example: false
payment_methodstring
The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.
Allowed: Credit Card | Cash | Test Payment Gateway | Manual
payment_provider_id
The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
One of:
Type: string
Example:
refunded_amountstring
The amount refunded from this transaction; always returns 0. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_ex_taxstring
The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_inc_taxstring
The value of shipping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
staff_notesstring
Any additional notes for staff.
<= 65535 characters
Example: Send Saturday
status_idinteger
The status ID of the order.
subtotal_ex_taxstring
Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
subtotal_inc_taxstring
Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
tax_provider_idstring
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.
Allowed: BasicTaxProvider | AvaTaxProvider |
customer_localestring
The customer’s locale.
Example: en
external_order_idstring
The external id of the order.
Example: external-order-id
total_ex_taxstring
Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
total_inc_taxstring
Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
wrapping_cost_ex_taxstring
The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
wrapping_cost_inc_taxstring
The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000

response

{
  "id": 218,
  "customer_id": 11,
  "date_created": "Tue, 05 Mar 2019 21:40:11 +0000",
  "date_modified": "Mon, 11 Mar 2019 15:17:25 +0000",
  "date_shipped": "",
  "status_id": 7,
  "status": "Awaiting Payment",
  "subtotal_ex_tax": "62.6793",
  "subtotal_inc_tax": "67.8400",
  "subtotal_tax": "4.4000",
  "base_shipping_cost": "12.0000",
  "shipping_cost_ex_tax": "11.0900",
  "shipping_cost_inc_tax": "12.0000",
  "shipping_cost_tax": "0.9100",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "64.5300",
  "total_inc_tax": "69.8400",
  "total_tax": "5.3100",
  "items_total": 4,
  "items_shipped": 0,
  "payment_method": "Cash",
  "payment_provider_id": "",
  "payment_status": "authorized",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "ip_address_v6": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": "5.0000",
  "coupon_discount": "5.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": "0",
  "cart_id": "7e48f7ef-2e88-4817-aea4-b0ed01490114",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": 78108,
    "country": "United States",
    "country_iso2": "US",
    "phone": 1234567890,
    "email": "janedoe@example.com",
    "form_fields": [
      {
        "name": "Delivery Instructions",
        "value": "Leave in backyard"
      }
    ]
  },
  "is_email_opt_in": false,
  "credit_card_type": null,
  "order_source": "external",
  "channel_id": 1,
  "external_source": null,
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/products",
    "resource": "/orders/218/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/shippingaddresses",
    "resource": "/orders/218/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/coupons",
    "resource": "/orders/218/coupons"
  },
  "external_id": null,
  "external_merchant_id": null,
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "",
  "store_default_to_transactional_exchange_rate": "1.0000000000",
  "custom_status": "Awaiting Payment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Multiple Items

{
  "id": 247,
  "customer_id": 11,
  "date_created": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_modified": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_shipped": "",
  "status_id": 11,
  "status": "Awaiting Fulfillment",
  "subtotal_ex_tax": 924.47,
  "subtotal_inc_tax": 1000.74,
  "subtotal_tax": 76.27,
  "base_shipping_cost": 8,
  "shipping_cost_ex_tax": 7.39,
  "shipping_cost_inc_tax": 8,
  "shipping_cost_tax": 0.61,
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": 0,
  "handling_cost_ex_tax": 0,
  "handling_cost_inc_tax": 0,
  "handling_cost_tax": 0,
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": 0,
  "wrapping_cost_ex_tax": 0,
  "wrapping_cost_inc_tax": 0,
  "wrapping_cost_tax": 0,
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": 931.86,
  "total_inc_tax": 1008.74,
  "total_tax": 76.88,
  "items_total": 11,
  "items_shipped": 0,
  "payment_method": "Test Payment Gateway",
  "payment_provider_id": "",
  "payment_status": "captured",
  "refunded_amount": 0,
  "order_is_digital": false,
  "store_credit_amount": 0,
  "gift_certificate_amount": 0,
  "ip_address": "70.112.53.67",
  "geoip_country": "United States",
  "geoip_country_iso2": "US",
  "currency_id": 1,
  "currency_code\"": "USD",
  "currency_exchange_rate": 1,
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "BIN-45",
  "customer_message": "Custom Journal Added",
  "discount_amount": 0,
  "coupon_discount\"": 0,
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": 0,
  "cart_id": "8b84f622-faf1-4c10-887b-f5dff2f9eaf4",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78108",
    "country": "United States",
    "country_iso2": "US",
    "phone": "1234567890",
    "email": "janedoe@email.com",
    "form_fields": {
      "name": "Delivery Instructions",
      "value": "Leave in backyard"
    }
  },
  "is_email_opt_in": false,
  "credit_card_type": {},
  "order_source": "manual",
  "channel_id": 1,
  "external_source": {},
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/products",
    "resource": "/orders/247/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/shippingaddresses",
    "resource": "/orders/247/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/coupons",
    "resource": "/orders/247/coupons"
  },
  "external_id": {},
  "external_merchant_id": {},
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "USD",
  "store_default_to_transactional_exchange_rate": 1,
  "custom_status": "Awaiting Fulfillment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Archive an Order

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{order_id}

Request

Archives an order. To remove a single product from an order, see PUT /orders/{order_id}.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
order_id in path - integer - required
ID of the order.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Get a Count of Orders

GET https://api.bigcommerce.com/stores/{store_hash}/v2/orders/count

Request

Gets an array of orders in the store organized by order status.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/count' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Order Counter response collection.

Body

object | application/json

statusesarray[object]
countnumber
Total number of orders in the store.
Example: 45

response

{
  "statuses": [
    {
      "id": 0,
      "name": "Incomplete",
      "system_label": "Incomplete",
      "custom_label": "Incomplete - Testing",
      "system_description": "An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.",
      "count": 15,
      "sort_order": 0
    },
    {
      "id": 1,
      "name": "Pending",
      "system_label": "Pending",
      "custom_label": "Pending",
      "system_description": "Customer started the checkout process, but did not complete it.",
      "count": 4,
      "sort_order": 1
    },
    {
      "id": 7,
      "name": "Awaiting Payment",
      "system_label": "Awaiting Payment",
      "custom_label": "Awaiting Payment",
      "system_description": "Customer has completed checkout process, but payment has yet to be confirmed.",
      "count": 48,
      "sort_order": 2
    },
    {
      "id": 11,
      "name": "Awaiting Fulfillment",
      "system_label": "Awaiting Fulfillment",
      "custom_label": "Awaiting Fulfillment",
      "system_description": "Customer has completed the checkout process and payment has been confirmed.",
      "count": 31,
      "sort_order": 3
    },
    {
      "id": 9,
      "name": "Awaiting Shipment",
      "system_label": "Awaiting Shipment",
      "custom_label": "Awaiting Shipment",
      "system_description": "Order has been pulled and packaged, and is awaiting collection from a shipping provider.",
      "count": 1,
      "sort_order": 4
    },
    {
      "id": 8,
      "name": "Awaiting Pickup",
      "system_label": "Awaiting Pickup",
      "custom_label": "Awaiting Pickup",
      "system_description": "Order has been pulled, and is awaiting customer pickup from a seller-specified location.",
      "count": 0,
      "sort_order": 5
    },
    {
      "id": 3,
      "name": "Partially Shipped",
      "system_label": "Partially Shipped",
      "custom_label": "Partially Shipped",
      "system_description": "Only some items in the order have been shipped, due to some products being pre-order only or other reasons.",
      "count": 1,
      "sort_order": 6
    },
    {
      "id": 10,
      "name": "Completed",
      "system_label": "Completed",
      "custom_label": "Completed - Testing",
      "system_description": "Client has paid for their digital product and their file(s) are available for download.",
      "count": 11,
      "sort_order": 7
    },
    {
      "id": 2,
      "name": "Shipped",
      "system_label": "Shipped",
      "custom_label": "Shipped",
      "system_description": "Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action.",
      "count": 14,
      "sort_order": 8
    },
    {
      "id": 5,
      "name": "Cancelled",
      "system_label": "Cancelled",
      "custom_label": "Cancelled",
      "system_description": "Seller has cancelled an order, due to a stock inconsistency or other reasons.",
      "count": 5,
      "sort_order": 9
    },
    {
      "id": 6,
      "name": "Declined",
      "system_label": "Declined",
      "custom_label": "Declined",
      "system_description": "Seller has marked the order as declined for lack of manual payment, or other reasons.",
      "count": 0,
      "sort_order": 10
    },
    {
      "id": 4,
      "name": "Refunded",
      "system_label": "Refunded",
      "custom_label": "Refunded",
      "system_description": "Seller has used the Refund action.",
      "count": 2,
      "sort_order": 11
    },
    {
      "id": 13,
      "name": "Disputed",
      "system_label": "Disputed",
      "custom_label": "Disputed",
      "system_description": "Customer has initiated a dispute resolution process for the PayPal transaction that paid for the order.",
      "count": 0,
      "sort_order": 12
    },
    {
      "id": 12,
      "name": "Manual Verification Required",
      "system_label": "Manual Verification Required",
      "custom_label": "Manual Verification Required",
      "system_description": "Order is on hold while some aspect needs to be manually confirmed.",
      "count": 0,
      "sort_order": 13
    },
    {
      "id": 14,
      "name": "Partially Refunded",
      "system_label": "Partially Refunded",
      "custom_label": "Partially Refunded",
      "system_description": "Seller has partially refunded the order.",
      "count": 1,
      "sort_order": 14
    }
  ],
  "count": 133
}

Get All Orders

GET https://api.bigcommerce.com/stores/{store_hash}/v2/orders

Request

Gets a list of orders using the filter query.

Notes

The default sort is by order id, from lowest to highest.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
min_id in query - integer
The minimum order ID.
max_id in query - integer
The maximum order ID.
min_total in query - number
The minimum order total in floating point format. eg. 12.50
max_total in query - number
The maximum order total in floating point format. eg. 12.50
customer_id in query - integer
Customer ID.
email in query - string
The email of the customer.
status_id in query - integer
The status ID of the order. You can get the status id from the /orders endpoints.
cart_id in query - string
The cart ID of the order.
payment_method in query - string
The payment method used on the order.
min_date_created in query - string
Minimum date the order was created in RFC-2822 or ISO-8601.

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00
max_date_created in query - string
Maximum date the order was created in RFC-2822 or ISO-8601.

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00
min_date_modified in query - string
Minimum date the order was modified in RFC-2822 or ISO-8601.

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00
max_date_modified in query - string
Maximum date the order was modified in RFC-2822 or ISO-8601.

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00
page in query - number
The page to return in the response.
limit in query - number
Number of results to return.
sort in query - string
Field and direction to sort orders. To specify the direction, add :asc or :desc to the end of the query parameter. E.g. sort=date_created:desc.
is_deleted in query - boolean
If the order was deleted or archived.
channel_id in query - integer
The Channel ID of the Order.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

response

[
  {
    "id": 100,
    "customer_id": 20,
    "date_created": "Wed, 10 Jan 2018 21:05:30 +0000",
    "date_modified": "Wed, 05 Dec 2018 20:16:55 +0000",
    "date_shipped": "",
    "status_id": 11,
    "status": "Awaiting Fulfillment",
    "subtotal_ex_tax": "336.3200",
    "subtotal_inc_tax": "361.9500",
    "subtotal_tax": "25.6300",
    "base_shipping_cost": "0.0000",
    "shipping_cost_ex_tax": "0.0000",
    "shipping_cost_inc_tax": "0.0000",
    "shipping_cost_tax": "0.0000",
    "shipping_cost_tax_class_id": 2,
    "base_handling_cost": "0.0000",
    "handling_cost_ex_tax": "0.0000",
    "handling_cost_inc_tax": "0.0000",
    "handling_cost_tax": "0.0000",
    "handling_cost_tax_class_id": 2,
    "base_wrapping_cost": "0.0000",
    "wrapping_cost_ex_tax": "0.0000",
    "wrapping_cost_inc_tax": "0.0000",
    "wrapping_cost_tax": "0.0000",
    "wrapping_cost_tax_class_id": 3,
    "total_ex_tax": "361.9500",
    "total_inc_tax": "361.9500",
    "total_tax": "0.0000",
    "items_total": 17,
    "items_shipped": 0,
    "payment_method": "Credit Card",
    "payment_provider_id": "",
    "payment_status": "authorized",
    "refunded_amount": "0.0000",
    "order_is_digital": false,
    "store_credit_amount": "0.0000",
    "gift_certificate_amount": "0.0000",
    "ip_address": "00.000.000.000",
    "ip_address_v6": "",
    "geoip_country": "United States",
    "geoip_country_iso2": "US",
    "currency_id": 1,
    "currency_code": "USD",
    "currency_exchange_rate": "1.0000000000",
    "default_currency_id": 1,
    "default_currency_code": "USD",
    "staff_notes": "",
    "customer_message": "",
    "discount_amount": "0.0000",
    "coupon_discount": "0.0000",
    "shipping_address_count": 1,
    "is_deleted": false,
    "ebay_order_id": "0",
    "cart_id": "a8458391-ef68-4fe5-9ec1-442e6a767364",
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company": "",
      "street_1": "455 Main Street",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "janedoe@example.com",
      "form_fields": []
    },
    "is_email_opt_in": false,
    "credit_card_type": null,
    "order_source": "manual",
    "channel_id": 1,
    "external_source": "POS",
    "products": {
      "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/100/products",
      "resource": "/orders/100/products"
    },
    "shipping_addresses": {
      "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/100/shippingaddresses",
      "resource": "/orders/100/shippingaddresses"
    },
    "coupons": {
      "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/100/coupons",
      "resource": "/orders/100/coupons"
    },
    "external_id": null,
    "external_merchant_id": {},
    "tax_provider_id": "BasicTaxProvider",
    "store_default_currency_code": "",
    "store_default_to_transactional_exchange_rate": "1.0000000000",
    "custom_status": "Awaiting Fulfillment",
    "customer_locale": "en",
    "external_order_id": "external-order-id"
  }
]

Create an Order

POST https://api.bigcommerce.com/stores/{store_hash}/v2/orders

Request

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

Create an order with an existing catalog product or a custom product.

Required Fields

products or consignments
billing_address

When you create an order, the consignment(s) array allows you to create pickup consignments.

An order can have either a pickup or a shipping fulfillment method, but not both.
An order can have only one pickup consignment.

Choose from one of the following:

Create order with a shipping fulfillment method using shipping_addresses and products, i.e. legacy mode
Create order with a pickup fulfillment method using consignments, i.e. Consignment mode

You can fulfill an order with shipping or pickup, but not both.

This means that if the consignments array is present in the request, then none of the following may be present and vice-versa:

shipping_addresses
products

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

application/json

Products and Billing address only required for POST operation.

productsarray[]
shipping_addressesarray[object]
consignmentsobject

base_handling_coststring
The value of the base handling cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_shipping_coststring
The value of the base shipping cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_wrapping_coststring
The value of the base wrapping cost expressed as a floating point number to four decimal places in string format.
Example: 0.0000
billing_addressobject
channel_idinteger
Shows where the order originated. The channel_id will default to 1.
Example: 1
customer_idnumber
customer_messagestring
Message that the customer entered (number, options) -o the Order Comments box during checkout.
Example: Thank you
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.
default_currency_codestring
The currency code of the transactional currency the shopper pays in; writeable when multi-currency is enabled.
discount_amountstring
Amount of discount for this transaction. (Float, Float-As-String, Integer)
Example: 0.0000
ebay_order_idstring
If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
Example: 0
external_id
The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the external_id. You can update this field using 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.
One of:
Type: string
Example: null
external_merchant_id
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.
One of:
Type: string
Example: null
external_sourcestring
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.
Example: null
geoip_countrystring
The full name of the country where the customer made the purchase, based on the IP.
Example: United States
geoip_country_iso2string
The country where the customer made the purchase, in ISO2 format, based on the IP.
Example: US
handling_cost_ex_taxstring
The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
handling_cost_inc_taxstring
The value of the handling cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
ip_addressstring
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.
<= 30 characters
Example: 12.345.678.910
ip_address_v6string
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.
<= 39 characters
Example: 2001:db8:3333:4444:5555:6666:7777:8888
is_deletedboolean
Indicates whether the order was deleted (archived). Set to to true, to archive an order.
Example: false
items_shippednumber
The number of items that have been shipped.
Example: 0
items_totalnumber
The total number of items in the order.
Example: 1
order_is_digitalboolean
Whether this is an order for digital products.
Example: false
payment_methodstring
The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.
Allowed: Credit Card | Cash | Test Payment Gateway | Manual
payment_provider_id
The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
One of:
Type: string
Example:
refunded_amountstring
The amount refunded from this transaction; always returns 0. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_ex_taxstring
The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_inc_taxstring
The value of shipping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
staff_notesstring
Any additional notes for staff.
<= 65535 characters
Example: Send Saturday
status_idinteger
The status ID of the order.
subtotal_ex_taxstring
Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
subtotal_inc_taxstring
Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
tax_provider_idstring
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.
Allowed: BasicTaxProvider | AvaTaxProvider |
customer_localestring
The customer’s locale.
Example: en
external_order_idstring
The external id of the order.
Example: external-order-id
total_ex_taxstring
Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
total_inc_taxstring
Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
wrapping_cost_ex_taxstring
The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
wrapping_cost_inc_taxstring
The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000

Product with Variants

{
  "status_id": 0,
  "customer_id": 1,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": 78751,
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@example.com"
  },
  "products": [
    {
      "product_id": "118,",
      "quantity": "1,",
      "variant_id": 93
    }
  ]
}

Custom Product

{
  "status_id": 0,
  "customer_id": 1,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@email.com"
  },
  "products": [
    {
      "name": "BigCommerce Coffee Mug",
      "quantity": 1,
      "price_inc_tax": 50,
      "price_ex_tax": 45
    }
  ]
}

Product with Options

{
  "status_id": 0,
  "customer_id": 11,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@example.com"
  },
  "shipping_addresses": [
    {
      "first_name": "Trish",
      "last_name": "Test",
      "company": "Acme Pty Ltd",
      "street_1": "666 Sussex St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "email": "elsie@example.com"
    }
  ],
  "products": [
    {
      "product_id": 184,
      "quantity": 5,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "192"
        }
      ]
    }
  ]
}

Product with a Drop Down and a Text Field Modifier

{
  "status_id": 0,
  "customer_id": 11,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@example.com"
  },
  "shipping_addresses": [
    {
      "first_name": "Trish",
      "last_name": "Test",
      "company": "Acme Pty Ltd",
      "street_1": "666 Sussex St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "email": "elsie@example.com"
    }
  ],
  "products": [
    {
      "product_id": 184,
      "quantity": 5,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "Custom Message"
        }
      ]
    }
  ]
}

Multiple Products

{
  "status_id": 0,
  "customer_id": 11,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "janedoe@example.com"
  },
  "shipping_addresses": [
    {
      "first_name": "Trish",
      "last_name": "Test",
      "company": "Acme Pty Ltd",
      "street_1": "666 Sussex St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "email": "elsie@example.com"
    }
  ],
  "products": [
    {
      "name": "BigCommerce Poster",
      "quantity": 1,
      "price_inc_tax": 10.98,
      "price_ex_tax": 10
    },
    {
      "name": "BigCommerce Coffee Mug",
      "quantity": 1,
      "price_inc_tax": 50,
      "price_ex_tax": 45
    },
    {
      "product_id": 184,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "192"
        }
      ]
    }
  ]
}

Response

Order Response.

Body

application/json

Order object returned in responses.

idinteger
Read-only. The ID of the order.
Example: 118
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
date_shippedstring
A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822
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.
Example: a8458391-ef68-4fe5-9ec1-442e6a767364
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.
Example: Awaiting Fulfillment
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)
Example: 0.0000
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 2
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)
Example: 0.0000
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.)
Example: 3
payment_statusstring
A read-only value. Do not attempt to set or modify this value in a POST or PUT request.
Allowed: authorized | captured | capture pending | declined | held for review | paid | partially refunded | pending | refunded | void | void pending
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)
Example: 0.0000
gift_certificate_amountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 0.0000
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'.
Example: 1
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.
Example: USD
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)
Example: 1.0000000000
default_currency_idinteger
The transactional currency ID. A read-only value. Do not pass in a POST or PUT request.
Example: 1
default_currency_codestring
The currency code of the transactional currency the shopper pays in.
Example: EUR
store_default_currency_codestring
The currency code of the store's default currency.
Example: USD
store_default_to_transactional_exchange_ratestring
The exchange rate between the store's default currency and the transactional currency used in the order.
Example: 100.0000000000
coupon_discountstring
A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)
Example: 5.0000
shipping_address_countnumber
The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.
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.
Example: false
order_sourcestring
Orders submitted from the store's website will include a www value. Orders submitted with the Checkout API will be set to checkout_api.
Example: www, iPhone, Android, mobile, manual
consignmentsobject
productsobject
shipping_addressesobject
couponsobject
status_idinteger
The status ID of the order.
Example: 7
billing_addressobject

base_handling_coststring
The value of the base handling cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_shipping_coststring
The value of the base shipping cost. (Float, Float-As-String, Integer)
Example: 0.0000
base_wrapping_coststring
The value of the base wrapping cost expressed as a floating point number to four decimal places in string format.
Example: 0.0000
billing_addressobject
channel_idinteger
Shows where the order originated. The channel_id will default to 1.
Example: 1
customer_idnumber
customer_messagestring
Message that the customer entered (number, options) -o the Order Comments box during checkout.
Example: Thank you
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.
default_currency_codestring
The currency code of the transactional currency the shopper pays in; writeable when multi-currency is enabled.
discount_amountstring
Amount of discount for this transaction. (Float, Float-As-String, Integer)
Example: 0.0000
ebay_order_idstring
If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
Example: 0
external_id
The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the external_id. You can update this field using 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.
One of:
Type: string
Example: null
external_merchant_id
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.
One of:
Type: string
Example: null
external_sourcestring
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.
Example: null
geoip_countrystring
The full name of the country where the customer made the purchase, based on the IP.
Example: United States
geoip_country_iso2string
The country where the customer made the purchase, in ISO2 format, based on the IP.
Example: US
handling_cost_ex_taxstring
The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
handling_cost_inc_taxstring
The value of the handling cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
ip_addressstring
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.
<= 30 characters
Example: 12.345.678.910
ip_address_v6string
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.
<= 39 characters
Example: 2001:db8:3333:4444:5555:6666:7777:8888
is_deletedboolean
Indicates whether the order was deleted (archived). Set to to true, to archive an order.
Example: false
items_shippednumber
The number of items that have been shipped.
Example: 0
items_totalnumber
The total number of items in the order.
Example: 1
order_is_digitalboolean
Whether this is an order for digital products.
Example: false
payment_methodstring
The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.
Allowed: Credit Card | Cash | Test Payment Gateway | Manual
payment_provider_id
The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
One of:
Type: string
Example:
refunded_amountstring
The amount refunded from this transaction; always returns 0. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_ex_taxstring
The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
shipping_cost_inc_taxstring
The value of shipping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000
staff_notesstring
Any additional notes for staff.
<= 65535 characters
Example: Send Saturday
status_idinteger
The status ID of the order.
subtotal_ex_taxstring
Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
subtotal_inc_taxstring
Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
tax_provider_idstring
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.
Allowed: BasicTaxProvider | AvaTaxProvider |
customer_localestring
The customer’s locale.
Example: en
external_order_idstring
The external id of the order.
Example: external-order-id
total_ex_taxstring
Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
total_inc_taxstring
Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)
Example: 225.0000
wrapping_cost_ex_taxstring
The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)
Example: 0.0000
wrapping_cost_inc_taxstring
The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)
Example: 0.0000

response

{
  "id": 218,
  "customer_id": 11,
  "date_created": "Tue, 05 Mar 2019 21:40:11 +0000",
  "date_modified": "Mon, 11 Mar 2019 15:17:25 +0000",
  "date_shipped": "",
  "status_id": 7,
  "status": "Awaiting Payment",
  "subtotal_ex_tax": "62.6793",
  "subtotal_inc_tax": "67.8400",
  "subtotal_tax": "4.4000",
  "base_shipping_cost": "12.0000",
  "shipping_cost_ex_tax": "11.0900",
  "shipping_cost_inc_tax": "12.0000",
  "shipping_cost_tax": "0.9100",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "64.5300",
  "total_inc_tax": "69.8400",
  "total_tax": "5.3100",
  "items_total": 4,
  "items_shipped": 0,
  "payment_method": "Cash",
  "payment_provider_id": "",
  "payment_status": "authorized",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "ip_address_v6": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": "5.0000",
  "coupon_discount": "5.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": "0",
  "cart_id": "7e48f7ef-2e88-4817-aea4-b0ed01490114",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": 78108,
    "country": "United States",
    "country_iso2": "US",
    "phone": 1234567890,
    "email": "janedoe@example.com",
    "form_fields": [
      {
        "name": "Delivery Instructions",
        "value": "Leave in backyard"
      }
    ]
  },
  "is_email_opt_in": false,
  "credit_card_type": null,
  "order_source": "external",
  "channel_id": 1,
  "external_source": null,
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/products",
    "resource": "/orders/218/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/shippingaddresses",
    "resource": "/orders/218/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/218/coupons",
    "resource": "/orders/218/coupons"
  },
  "external_id": null,
  "external_merchant_id": null,
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "",
  "store_default_to_transactional_exchange_rate": "1.0000000000",
  "custom_status": "Awaiting Payment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Multiple Items

{
  "id": 247,
  "customer_id": 11,
  "date_created": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_modified": "Thu, 20 Jun 2019 16:07:08 +0000",
  "date_shipped": "",
  "status_id": 11,
  "status": "Awaiting Fulfillment",
  "subtotal_ex_tax": 924.47,
  "subtotal_inc_tax": 1000.74,
  "subtotal_tax": 76.27,
  "base_shipping_cost": 8,
  "shipping_cost_ex_tax": 7.39,
  "shipping_cost_inc_tax": 8,
  "shipping_cost_tax": 0.61,
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": 0,
  "handling_cost_ex_tax": 0,
  "handling_cost_inc_tax": 0,
  "handling_cost_tax": 0,
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": 0,
  "wrapping_cost_ex_tax": 0,
  "wrapping_cost_inc_tax": 0,
  "wrapping_cost_tax": 0,
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": 931.86,
  "total_inc_tax": 1008.74,
  "total_tax": 76.88,
  "items_total": 11,
  "items_shipped": 0,
  "payment_method": "Test Payment Gateway",
  "payment_provider_id": "",
  "payment_status": "captured",
  "refunded_amount": 0,
  "order_is_digital": false,
  "store_credit_amount": 0,
  "gift_certificate_amount": 0,
  "ip_address": "70.112.53.67",
  "geoip_country": "United States",
  "geoip_country_iso2": "US",
  "currency_id": 1,
  "currency_code\"": "USD",
  "currency_exchange_rate": 1,
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "BIN-45",
  "customer_message": "Custom Journal Added",
  "discount_amount": 0,
  "coupon_discount\"": 0,
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": 0,
  "cart_id": "8b84f622-faf1-4c10-887b-f5dff2f9eaf4",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "555 East Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78108",
    "country": "United States",
    "country_iso2": "US",
    "phone": "1234567890",
    "email": "janedoe@email.com",
    "form_fields": {
      "name": "Delivery Instructions",
      "value": "Leave in backyard"
    }
  },
  "is_email_opt_in": false,
  "credit_card_type": {},
  "order_source": "manual",
  "channel_id": 1,
  "external_source": {},
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/products",
    "resource": "/orders/247/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/shippingaddresses",
    "resource": "/orders/247/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/coupons",
    "resource": "/orders/247/coupons"
  },
  "external_id": {},
  "external_merchant_id": {},
  "tax_provider_id": "BasicTaxProvider",
  "store_default_currency_code": "USD",
  "store_default_to_transactional_exchange_rate": 1,
  "custom_status": "Awaiting Fulfillment",
  "customer_locale": "en",
  "external_order_id": "external-order-id"
}

Delete All Orders

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/orders

Request

Archives all orders.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
limit in query - number
Number of results to return.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Orders V2

Order

Currency Fields

Get an Order

Request

Authentication

Parameters

example

Response

Body

idinteger

date_modifiedstring

date_shippedstring

cart_idstring

statusstring

subtotal_taxstring

shipping_cost_taxstring

shipping_cost_tax_class_idinteger

handling_cost_taxstring

handling_cost_tax_class_idinteger

wrapping_cost_taxstring

wrapping_cost_tax_class_idinteger

payment_statusstring

store_credit_amountstring

gift_certificate_amountstring

currency_idinteger

currency_codestring

currency_exchange_ratestring

default_currency_idinteger

default_currency_codestring

store_default_currency_codestring

store_default_to_transactional_exchange_ratestring

coupon_discountstring

shipping_address_countnumber

is_email_opt_inboolean

order_sourcestring

consignmentsobject

productsobject

shipping_addressesobject

couponsobject

status_idinteger

billing_addressobject

base_handling_coststring

base_shipping_coststring

base_wrapping_coststring

billing_addressobject

channel_idinteger

customer_idnumber

customer_messagestring

date_createdstring

default_currency_codestring

discount_amountstring

ebay_order_idstring

external_id

external_merchant_id

external_sourcestring

geoip_countrystring

geoip_country_iso2string

handling_cost_ex_taxstring

handling_cost_inc_taxstring

ip_addressstring

ip_address_v6string

is_deletedboolean

items_shippednumber

items_totalnumber

order_is_digitalboolean

payment_methodstring

payment_provider_id

refunded_amountstring

shipping_cost_ex_taxstring

shipping_cost_inc_taxstring

staff_notesstring

status_idinteger

subtotal_ex_taxstring

subtotal_inc_taxstring

tax_provider_idstring

customer_localestring

external_order_idstring

total_ex_taxstring

total_inc_taxstring