Docs
Management API
Orders

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 /orders/{order_id}

Request

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

Authentication

  • X-Auth-Token in header

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.
  • include in query - array
    • consignments
      • include the response returned from the request to the /orders/{order_id}/consignments endpoint. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and may not be supported in the future.
    • consignments.line_items
      • include the response returned from the request to the /orders/{order_id}/products endpoint in consignments. This implies include=consignments. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and will be removed in the future.
    • fees
      • include the response returned from the request to the /orders/{order_id}/fees endpoint.
    Type: array[string]

    Allowed: consignments | consignments.line_items | fees

  • consignment_structure in query - string
    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: object

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: {{token}}'

Response

Order Response.

Body

object | application/json
Order object returned in responses.

  • id    integer

    Read-only. The ID of the order.
    Example: 118

  • date_modified    string

    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_shipped    string

    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_id    string

    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

  • status    string

    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_tax    string

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_status    string

    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_amount    string

    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_amount    string

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

  • currency_id    integer

    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_code    string

    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_rate    string

    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_id    integer

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

  • default_currency_code    string

    The currency code of the transactional currency the shopper pays in.
    Example: EUR

  • store_default_currency_code    string

    The currency code of the storeʼs default currency.
    Example: USD

  • store_default_to_transactional_exchange_rate    string

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

  • coupon_discount    string

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

  • shipping_address_count    number

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

  • is_deleted    boolean

    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_tax_inclusive_pricing    boolean

    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.

  • is_email_opt_in    boolean

    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.

  • order_source    string

    Reflects the origin of the order. It can affect the order’s icon and source as defined in the control panel listing. Allowed values: www (Desktop) | iphone (Iphone) | ipad (Ipad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | checkout_api (Checkout API) | buybutton (Buy Button) | amazon (Amazon) | ebay (Ebay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

    Example: www

  • consignments    object
    read-only

  • products    object
    read-only

  • shipping_addresses    object
    read-only

  • coupons    object
    read-only

  • status_id    integer

    The status ID of the order.
    Example: 7

  • billing_address    object

  • fees    array[object]

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • channel_id    integer

    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.
    Example: 1

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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.

  • discount_amount    string

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

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    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)

    Example: 0.0000

  • shipping_cost_inc_tax    string

    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)

    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

    The value of the wrapping cost, including tax. The value can't be negative. (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",

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",

Update an Order

PUT /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.

After the update, the PUT request clears all discounts and promotions applied to the changed order line items. Since the order data syncs with other ERP systems, like Amazon or eBay, the updated order returns to the default setting, removing any applied discounts.

To update order fees, include the fee id in the request body along with all relevant fee fields. Fees not included will be deleted. Fees with an id will be updated, and fees without an id will be created as new.

Notes

  • Sub-resources like products in the /v2/orders PUT request behave like PATCH, updating only the provided fields. Fees, however, follow standard PUT semantics and fees in the request body will fully replace existing ones. To retain an existing fee, include it in the body with its associated id.
  • The values for cost_ex_tax, cost_inc_tax and cost_tax in the fees payload should reflect the tax rate associated with the tax_class_id. For a 10% tax rate, the difference between cost_inc_tax and cost_ex_tax should be 10%. If no tax_class_id is provided, the store's default "tax class for fee" will apply. Incorrect data may lead to issues in downstream operations like refunds.

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

Authentication

  • X-Auth-Token in header

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.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • billing_address    object

  • channel_id    integer

    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.
    Example: 1

  • consignments    object

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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_code    string
    read-only

    A read-only field displays the currency code of the transactional currency the shopper uses.

  • discount_amount    string

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

  • order_source    string

    The order_source reflects the origin of the order. It will indicate whether the order was created by one of the following:

    • storefront
    • control panel
    • manual order
    • /v2/orders API
    • Checkout API
    • or by an integration with an external platform such as Facebook by Meta or Amazon.
    Example: www

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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. Also, this code will not affect the total_sold on products for imported orders.
    • If you do not provide a value, then it will default to null.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • products    array[]

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    The value of shipping cost, excluding tax. The value can't be negative. (Float, Float-As-String, Integer)
    Example: 0.0000

  • shipping_cost_inc_tax    string

    The value of shipping cost, including tax. The value can't be negative. (Float, Float-As-String, Integer)
    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • shipping_addresses    array[object]

  • status_id    integer

    The status ID of the order.

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string or null

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

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

  • fees    array[object]

Requests

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

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": [
{
"id": 117,
"product_id": 123,
"quantity": 1,
"product_options": [
{
"id": 56,
"value": 12
}
],
"price_inc_tax": 12.45,
"price_ex_tax": 10.12
}
]
}

Adding a new fee (no ID) while retaining existing fees (with ID)

{
"fees": [
{
"type": "custom_fee",
"display_name_customer": "C Fee",
"source": "AA",
"cost_ex_tax": "22.5000",
"cost_inc_tax": "25.0000"
},
{
"id": 1,
"type": "custom_fee",
"display_name_customer": "A Fee",
"source": "AA",
"cost_exc_tax": "12.3000",
"cost_inc_tax": "12.3000",
"tax_class_id": 22
},
{
"id": 2,
"type": "custom_fee",
"display_name_merchant": "B Fee",
"source": "AA",
"cost_ex_tax": "4.0000",
"cost_tax": "8.0000",
"tax_class_id": null
}
]
}

Updating order fees (all fees provided with IDs and attributes)

{
"fees": [
{
"id": 3,
"type": "custom_fee",
"display_name_customer": "C Fee Updated",
"source": "AA",
"cost_ex_tax": "20.0000",
"cost_inc_tax": "25.0000"
},
{
"id": 1,
"type": "custom_fee",
"display_name_customer": "A Fee Updated",
"source": "AA",
"cost_exc_tax": "10.0000",
"cost_inc_tax": "15.0000",
"tax_class_id": 1
},
{
"id": 2,
"type": "custom_fee",
"display_name_merchant": "B Fee Updated",
"source": "AA",
"cost_ex_tax": "5.0000",
"cost_tax": "8.0000",
"tax_class_id": 2

Deleting a fee from the order (fee missing from the payload will be deleted)

{
"fees": [
{
"id": 3,
"type": "custom_fee",
"display_name_customer": "C Fee Updated",
"source": "AA",
"cost_ex_tax": "20.0000",
"cost_inc_tax": "25.0000"
}
]
}

Deleting all fees from the order

{
"fees": []
}

Response

Order Response.

Body

object | application/json
Order object returned in responses.

  • id    integer

    Read-only. The ID of the order.
    Example: 118

  • date_modified    string

    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_shipped    string

    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_id    string

    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

  • status    string

    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_tax    string

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_status    string

    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_amount    string

    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_amount    string

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

  • currency_id    integer

    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_code    string

    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_rate    string

    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_id    integer

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

  • default_currency_code    string

    The currency code of the transactional currency the shopper pays in.
    Example: EUR

  • store_default_currency_code    string

    The currency code of the storeʼs default currency.
    Example: USD

  • store_default_to_transactional_exchange_rate    string

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

  • coupon_discount    string

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

  • shipping_address_count    number

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

  • is_deleted    boolean

    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_tax_inclusive_pricing    boolean

    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.

  • is_email_opt_in    boolean

    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.

  • order_source    string

    Reflects the origin of the order. It can affect the order’s icon and source as defined in the control panel listing. Allowed values: www (Desktop) | iphone (Iphone) | ipad (Ipad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | checkout_api (Checkout API) | buybutton (Buy Button) | amazon (Amazon) | ebay (Ebay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

    Example: www

  • consignments    object
    read-only

  • products    object
    read-only

  • shipping_addresses    object
    read-only

  • coupons    object
    read-only

  • status_id    integer

    The status ID of the order.
    Example: 7

  • billing_address    object

  • fees    array[object]

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • channel_id    integer

    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.
    Example: 1

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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.

  • discount_amount    string

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

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    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)

    Example: 0.0000

  • shipping_cost_inc_tax    string

    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)

    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

    The value of the wrapping cost, including tax. The value can't be negative. (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",

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",

Archive an Order

DELETE /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

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: {{token}}'

Response

Get a Count of Orders

GET /orders/count

Request

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

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • 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 display name of the payment method used on the order. For example, Manual, Credit Card, cash, Test Payment Gateway, etc.'
  • 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

  • channel_id in query - integer
    The channel ID of the sales channel the shopper used to place the order.
  • external_order_id in query - string
    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.

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: {{token}}'

Response

Order Counter response collection.

Body

object | application/json

  • statuses    array[object]

  • count    number

    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",

Get All Orders

GET /orders

Request

Gets a list of orders using the filter query.

Notes

  • The default sort is by order id, from lowest to highest.
  • By default, requests sent without parameters will only return 50 orders.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • 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 display name of the payment method used on the order. For example, Manual, Credit Card, cash, Test Payment Gateway, etc.'
  • 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 with default of 1 - number
    The page to return in the response.
  • limit in query with default of 50 - 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.

    Allowed: id | customer_id | date_created | date_modified | status_id | channel_id | external_id

  • channel_id in query - integer
    The channel ID of the sales channel the shopper used to place the order.
  • include in query - array
    • consignments
      • include the response returned from the request to the /orders/{order_id}/consignments endpoint. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and may not be supported in the future.
    • consignments.line_items
      • include the response returned from the request to the /orders/{order_id}/products endpoint in consignments. This implies include=consignments. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and will be removed in the future.
    • fees
      • include the response returned from the request to the /orders/{order_id}/fees endpoint.
    Type: array[string]

    Allowed: consignments | consignments.line_items | fees

  • consignment_structure in query - string
    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: object

  • external_order_id in query - string
    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.

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: {{token}}'

Response

Body

array | application/json

  • id    integer

    Read-only. The ID of the order.
    Example: 118

  • date_modified    string

    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_shipped    string

    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_id    string

    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

  • status    string

    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_tax    string

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_status    string

    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_amount    string

    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_amount    string

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

  • currency_id    integer

    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_code    string

    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_rate    string

    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_id    integer

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

  • default_currency_code    string

    The currency code of the transactional currency the shopper pays in.
    Example: EUR

  • store_default_currency_code    string

    The currency code of the storeʼs default currency.
    Example: USD

  • store_default_to_transactional_exchange_rate    string

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

  • coupon_discount    string

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

  • shipping_address_count    number

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

  • is_deleted    boolean

    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_tax_inclusive_pricing    boolean

    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.

  • is_email_opt_in    boolean

    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.

  • order_source    string

    Reflects the origin of the order. It can affect the order’s icon and source as defined in the control panel listing. Allowed values: www (Desktop) | iphone (Iphone) | ipad (Ipad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | checkout_api (Checkout API) | buybutton (Buy Button) | amazon (Amazon) | ebay (Ebay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

    Example: www

  • consignments    object
    read-only

  • products    object
    read-only

  • shipping_addresses    object
    read-only

  • coupons    object
    read-only

  • status_id    integer

    The status ID of the order.
    Example: 7

  • billing_address    object

  • fees    array[object]

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • channel_id    integer

    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.
    Example: 1

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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.

  • discount_amount    string

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

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    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)

    Example: 0.0000

  • shipping_cost_inc_tax    string

    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)

    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

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

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",

Create an Order

POST /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:

  1. Create order with a shipping fulfillment method using shipping_addresses and products, i.e. legacy mode
  2. 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

Include the fees object along with all its attributes in the request to create order-level fees for the newly created order.

Notes

  • The values for cost_ex_tax, cost_inc_tax and cost_tax in the fees payload should reflect the tax rate associated with the tax_class_id. For a 10% tax rate, the difference between cost_inc_tax and cost_ex_tax should be 10%. If no tax_class_id is provided, the store's default "tax class for fee" will apply. Incorrect data may lead to issues in downstream operations like refunds.

The V2 Orders API will not trigger the typical Order Email when creating orders. To create an order that does trigger this email, you can instead create a cart and convert that cart into an order.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
  • include in query - array
    • consignments
      • include the response returned from the request to the /orders/{order_id}/consignments endpoint. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and may not be supported in the future.
    • consignments.line_items
      • include the response returned from the request to the /orders/{order_id}/products endpoint in consignments. This implies include=consignments. You should also specify consignment_structure=object as a request parameter when including consignments. The default array structure provided is legacy and will be removed in the future.
    • fees
      • include the response returned from the request to the /orders/{order_id}/fees endpoint.
    Type: array[string]

    Allowed: consignments | consignments.line_items | fees

  • consignment_structure in query - string
    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: object

Body

object | application/json
Products and Billing address only required for POST operation.

  • billing_address    object

  • default_currency_code    string

    The currency code of the transactional currency the shopper pays in is writable when multi-currency is enabled.

  • products    array[]

  • shipping_addresses    array[object]

  • consignments    object

  • fees    array[object]

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • channel_id    integer

    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.
    Example: 1

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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.

  • discount_amount    string

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

  • order_source    string

    The order_source reflects the origin of the order. It will indicate whether the order was created by one of the following:

    • storefront
    • control panel
    • manual order
    • /v2/orders API
    • Checkout API
    • or by an integration with an external platform such as Facebook by Meta or Amazon.
    Example: www

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    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)

    Example: 0.0000

  • shipping_cost_inc_tax    string

    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)

    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • status_id    integer

    The status ID of the order.

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

    The value of the wrapping cost, including tax. The value can't be negative. (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"

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"

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"

Create an order with fees (include the fees object as shown with rest of the payload)

{
"fees": [
{
"type": "custom_fee",
"display_name_customer": "D Fee",
"source": "AA",
"cost_ex_tax": "22.5000",
"cost_inc_tax": "25.0000",
"tax_class_id": 22
},
{
"type": "custom_fee",
"display_name_customer": "E Fee",
"source": "AA",
"cost_exc_tax": "12.3000",
"cost_inc_tax": "12.3000",
"tax_class_id": null
},
{
"type": "custom_fee",
"display_name_merchant": "F Fee",
"source": "AA",
"cost_ex_tax": "4.0000",
"cost_tax": "8.0000"
}
]
}

Response

Order Response.

Body

object | application/json
Order object returned in responses.

  • id    integer

    Read-only. The ID of the order.
    Example: 118

  • date_modified    string

    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_shipped    string

    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_id    string

    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

  • status    string

    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_tax    string

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_tax    string

    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_id    integer

    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_status    string

    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_amount    string

    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_amount    string

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

  • currency_id    integer

    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_code    string

    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_rate    string

    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_id    integer

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

  • default_currency_code    string

    The currency code of the transactional currency the shopper pays in.
    Example: EUR

  • store_default_currency_code    string

    The currency code of the storeʼs default currency.
    Example: USD

  • store_default_to_transactional_exchange_rate    string

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

  • coupon_discount    string

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

  • shipping_address_count    number

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

  • is_deleted    boolean

    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_tax_inclusive_pricing    boolean

    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.

  • is_email_opt_in    boolean

    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.

  • order_source    string

    Reflects the origin of the order. It can affect the order’s icon and source as defined in the control panel listing. Allowed values: www (Desktop) | iphone (Iphone) | ipad (Ipad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | checkout_api (Checkout API) | buybutton (Buy Button) | amazon (Amazon) | ebay (Ebay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

    Example: www

  • consignments    object
    read-only

  • products    object
    read-only

  • shipping_addresses    object
    read-only

  • coupons    object
    read-only

  • status_id    integer

    The status ID of the order.
    Example: 7

  • billing_address    object

  • fees    array[object]

  • base_handling_cost    string

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

  • base_shipping_cost    string

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

  • base_wrapping_cost    string

    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.
    Example: 0.0000

  • channel_id    integer

    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.
    Example: 1

  • customer_id    number

  • customer_message    string

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

  • date_created    string

    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.

  • discount_amount    string

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

  • ebay_order_id    string

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

  • external_id    string or null
    read-only

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

  • external_merchant_id    string 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_source    string 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.

  • geoip_country    string

    The full name of the country where the customer made the purchase, based on the IP.
    Example: United States

  • geoip_country_iso2    string

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

  • handling_cost_ex_tax    string

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

  • handling_cost_inc_tax    string

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

  • ip_address    string

    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_v6    string

    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

  • items_shipped    number

    The number of items that have been shipped.

  • items_total    number

    The total number of items in the order.
    Example: 1

  • order_is_digital    boolean

    Whether this is an order for digital products.

  • payment_method    string

    The payment method for this order. For example, 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

  • refunded_amount    string

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

  • shipping_cost_ex_tax    string

    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)

    Example: 0.0000

  • shipping_cost_inc_tax    string

    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)

    Example: 0.0000

  • staff_notes    string

    Any additional notes for staff.
    <= 65535 characters
    Example: Send Saturday

  • subtotal_ex_tax    string

    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)
    Example: 225.0000

  • subtotal_inc_tax    string

    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)
    Example: 225.0000

  • tax_provider_id    string

    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.

  • customer_locale    string

    The customer’s locale.
    Example: en

  • external_order_id    string

    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.
    Example: external-order-id

  • total_ex_tax    string

    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)
    Example: 225.0000

  • total_inc_tax    string

    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)
    Example: 225.0000

  • wrapping_cost_ex_tax    string

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

  • wrapping_cost_inc_tax    string

    The value of the wrapping cost, including tax. The value can't be negative. (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",

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",

Delete All Orders

DELETE /orders

Request

Archives all orders.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • limit in query with default of 50 - 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: {{token}}'

Response

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete a MetafieldGet an Order