Skip to navigation
RESTAdminManagementOrders

Update Order

Updates an Order. Send only the fields you want to change. Top-level order fields and sub-resources such as products and shipping_addresses behave like a PATCH: omitted fields keep their current values.

Products

  • To add a product to an existing order, omit the order product id. Include product_options when adding a product with variants.
  • To update a product in an order, include the order product id. Only the fields you send are changed.
  • To remove a product from an order, set that product’s quantity to 0. The line item stays on the order with a quantity of 0 and no longer counts toward items_total or the order totals.
  • When you change a line item’s quantity, price, variant, product, product options, or gift wrapping, the API removes all discounts and promotions from that line item. If you sync orders to an external system, such as an ERP or marketplace, sync the order again after the update.

Fees

Fees follow standard PUT semantics: the fees array in the request replaces all existing fees on the order. To keep an existing fee, include it with its id. Fees without an id are created. Fees you omit are deleted. Send "fees": [] to remove all fees.

The values for cost_ex_tax, cost_inc_tax, and cost_tax in each fee should reflect the tax rate of the fee’s tax_class_id. For a 10% tax rate, cost_inc_tax should be 10% higher than cost_ex_tax. If you omit tax_class_id, the store’s default tax class for fees applies. Incorrect values can cause problems in downstream operations such as refunds.

Shipping addresses

To update an existing shipping address, include its id in the shipping_addresses entry. Entries without an id are added as new shipping addresses.

Archiving

Set is_deleted to true to archive the order. This has the same effect as the Archive an order endpoint. Set it to false to restore an archived order.

Read-only fields

The request rejects external_id and external_merchant_id with a 400 error. Computed fields such as items_total, order_is_digital, and tax_provider_id are accepted but ignored.

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

Note

  • If historical orders processed on another eCommerce platform are being migrated to BigCommerce, supply the external_source field with the code M-MIG. This code will exclude the historical orders from the store’s GMV/order count, which factors into pricing.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Ordersmodifystore_v2_orders
Ordersread-onlystore_v2_orders_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

order_idintegerRequired
ID of the order.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Query parameters

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

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

Allowed values:

Request

This endpoint expects an object.
base_handling_coststringOptional

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

base_shipping_coststringOptional

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

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

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.

consignmentsobjectOptional
customer_idintegerOptional

The ID of the customer placing the order. Use 0 for a guest order.

customer_messagestringOptional

Message that the customer entered in the Order Comments box during checkout.

date_createdstringOptional

The date the order was created, formatted in the RFC-2822 standard, e.g., Tue, 20 Nov 2012 00:00:00 +0000. Supply this value to support the migration of historical orders. If omitted, the existing value is unchanged.

discount_amountstringOptional

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

order_sourcestringOptional

Reflects the origin of the order, such as the storefront, the control panel, a manual order, the Orders API, the Checkout API, or an integration with an external platform. It can affect the order’s icon and source shown in the control panel order list. Orders created with the API default to external.

Allowed values: www (Desktop) | iphone (iPhone) | ipad (iPad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | buybutton (Buy Button) | amazon (Amazon) | ebay (eBay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

ebay_order_idstringOptional

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

external_sourcestring or nullOptional

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_countrystringOptional
The full name of the country where the customer made the purchase, based on the IP.
geoip_country_iso2stringOptional
The country where the customer made the purchase, in ISO2 format, based on the IP.
handling_cost_ex_taxstringOptional

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

handling_cost_inc_taxstringOptional

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

ip_addressstringOptional<=30 characters

IPv4 Address of the customer, if known.

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

ip_address_v6stringOptional<=39 characters

IPv6 Address of the customer, if known.

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

items_shippeddoubleOptional
The number of items that have been shipped.
is_deletedbooleanOptional

Indicates whether the order is archived. Set to true to archive the order, which has the same effect as the Archive an order endpoint. Set to false to restore an archived order.

payment_methodstringOptional

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

payment_provider_idstring or doubleOptional

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

productslist of objectsOptional
refunded_amountstringOptional

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

shipping_cost_ex_taxstringOptional

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

shipping_cost_inc_taxstringOptional

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

staff_notesstringOptional<=65535 characters
Any additional notes for staff.
shipping_addresseslist of objectsOptional
status_idintegerOptional
The status ID of the order.
subtotal_ex_taxstringOptional

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

subtotal_inc_taxstringOptional

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)

customer_localestringOptional

The customer’s locale. The supported formats are:

  • 2-char lowercase characters. e.g., en
  • 3-char lowercase characters. e.g., asa
  • 5-char the language code is 2 lowercase characters and the region code is 2 uppercase characters, with - in the middle. e.g., en-US
  • 6-char the language code is 2 lowercase character and the region code is three digit number, with - in the middle. e.g., es-419
external_order_idstring or nullOptional
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.
total_ex_taxstringOptional

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

total_inc_taxstringOptional

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)

wrapping_cost_ex_taxstringOptional

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

wrapping_cost_inc_taxstringOptional

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

feeslist of objectsOptional

Response

Order Response.
backorder_shipping_expectation_messagestring or nullOptional

The shipping expectation message shown to the customer when the order contains a backordered item. null when the order has no backordered items.

base_handling_coststringOptional

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

base_shipping_coststringOptional

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

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

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

channel_idintegerOptional

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.

consignmentsobjectOptional
coupon_discountstringOptional

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

couponsobjectOptionalRead-only
currency_codestringOptional

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

currency_exchange_ratestringOptional

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

currency_idintegerOptional

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

customer_iddoubleOptional

The ID of the customer who placed the order. 0 indicates a guest checkout. Use this ID with the Customers API to look up customer attributes that aren’t stored on the order, such as tax_exempt_category.

customer_localestringOptional

The customer’s locale. The supported formats are:

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

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

date_createdstringOptional

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

date_modifiedstringOptional

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

date_shippedstringOptional

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

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

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

discount_amountstringOptional

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

ebay_order_idstringOptional

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

external_idstring or nullOptionalRead-only

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

external_merchant_idstring or nullOptional

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

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

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

  • When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square).
  • If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing.
  • If you do not provide a value, then it will default to null.
feesobject or list of objectsOptional
geoip_countrystringOptional
The full name of the country where the customer made the purchase, based on the IP.
geoip_country_iso2stringOptional
The country where the customer made the purchase, in ISO2 format, based on the IP.
gift_certificate_amountstringOptional

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

handling_cost_ex_taxstringOptional

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

handling_cost_inc_taxstringOptional

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

handling_cost_taxstringOptional

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

handling_cost_tax_class_idintegerOptional

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

idintegerOptional

Read-only. The ID of the order.

ip_addressstringOptional<=30 characters

IPv4 Address of the customer, if known.

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

ip_address_v6stringOptional<=39 characters

IPv6 Address of the customer, if known.

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

is_deletedbooleanOptional

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

is_email_opt_inbooleanOptional

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

is_tax_inclusive_pricingbooleanOptional

Indicate whether the order’s base prices include tax.

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

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

items_shippeddoubleOptional
The number of items that have been shipped.
items_totaldoubleOptional
The total number of items in the order.
order_is_digitalbooleanOptional
Whether this is an order for digital products.
order_sourcestringOptional

Reflects the origin of the order, such as the storefront, the control panel, a manual order, the Orders API, the Checkout API, or an integration with an external platform. It can affect the order’s icon and source shown in the control panel order list. Orders created with the API default to external.

Allowed values: www (Desktop) | iphone (iPhone) | ipad (iPad) | android (Android) | mobile (Mobile) | manual (manual order) | external (Orders API) | buybutton (Buy Button) | amazon (Amazon) | ebay (eBay) | facebookshop (Facebook Shop) | facebookcheckout (Facebook Checkout) | facebookmarketplace (Facebook Marketplace) | pinterest (Pinterest) | socialshop (Social Shop)

payment_methodstringOptional

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

payment_provider_idstring or doubleOptional

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

payment_statusenumOptional

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

productsobjectOptionalRead-only
refunded_amountstringOptional

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

shipping_address_countdoubleOptional

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

shipping_addressesobjectOptionalRead-only
shipping_cost_ex_taxstringOptional

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

shipping_cost_inc_taxstringOptional

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

shipping_cost_taxstringOptional

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

shipping_cost_tax_class_idintegerOptional

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

staff_notesstringOptional<=65535 characters
Any additional notes for staff.
statusstringOptional

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

status_idintegerOptional
The status ID of the order.
store_credit_amountstringOptional

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

store_default_currency_codestringOptional

The currency code of the storeʼs default currency.

store_default_to_transactional_exchange_ratestringOptional

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

subtotal_ex_taxstringOptional

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

subtotal_inc_taxstringOptional

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

subtotal_taxstringOptional

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

tax_provider_idstringOptional

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

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

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

total_ex_taxstringOptional

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

total_inc_taxstringOptional

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

total_taxstringOptional

Total tax amount for the order. A value of 0 doesn’t indicate a tax-exempt customer; tax-exempt status lives in the tax_exempt_category field of the customer record, not on the order.

wrapping_cost_ex_taxstringOptional

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

wrapping_cost_inc_taxstringOptional

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

wrapping_cost_taxstringOptional

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

wrapping_cost_tax_class_idintegerOptional

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

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

Errors

404
Not Found Error