put

/orders/{order_id}

Updates an Order.

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

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

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

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

Authorization

apiKey - X-Auth-Token

Request Parameters

1 Path Parameter
2 Headers

Request Body

4 Examples
Schema
object

Order properties used in PUT and POST requests and responses.

$schema: http://json-schema.org/draft-04/schema#
products
array[anyOf]
shipping_addresses
object

Shipping Address properties common to all requests and responses.

base_handling_cost
string

The value of the base handling cost. (Float, Float-As-String, Integer)

1 validation
base_shipping_cost
string

The value of the base shipping cost. (Float, Float-As-String, Integer)

1 validation
base_wrapping_cost
oneOf

The value of the base wrapping cost. (Float, Float-As-String, Integer)

billing_address
object

Required to create an order.

channel_id
integer

Shows where the order originated. The channel_id will default to 1.

1 validation
customer_id
number
customer_message
string

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

1 validation
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

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

discount_amount
string

Amount of discount for this transaction. (Float, Float-As-String, Integer)

1 validation
ebay_order_id
string

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

1 validation
external_id
oneOf

ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ‘external_id’ cannot be written to. Please remove it from your request before trying again. It can not be overwritten once set.

external_source
oneOf

This value identifies an external system that generated the order and submitted it to BigCommerce via 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.

1 validation
geoip_country_iso2
string

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

1 validation
handling_cost_ex_tax
string

The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_inc_tax
string

The value of the handling cost, including tax. (Float, Float-As-String, Integer)

1 validation
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.

2 validations
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.

2 validations
is_deleted
boolean

Indicates whether the order was deleted (archived). Set to to true, to archive an order.

1 validation
items_shipped
number

The number of items that have been shipped.

1 validation
items_total
number

The total number of items in the order.

1 validation
order_is_digital
boolean

Whether this is an order for digital products.

1 validation
payment_method
string

The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.

1 validation
payment_provider_id
string or number

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

1 validation
refunded_amount
string

The amount refunded from this transaction. (Float, Float-As-String, Integer)

1 validation
shipping_cost_ex_tax
string

The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_inc_tax
string

The value of shipping cost, including tax. (Float, Float-As-String, Integer)

1 validation
staff_notes
string

Any additional notes for staff.

1 validation
status_id
integer

The status ID of the order.

subtotal_ex_tax
string

Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_inc_tax
string

Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
tax_provider_id
string

BasicTaxProvider - Tax is set to manual.

AvaTaxProvider - This is for when the tax provider has been set to automatic and the order was NOT created by the API. Used for Avalara.

“” (blank) - When the tax provider is unknown. This includes legacy orders and orders previously created via API. This can be set when creating an order using a POST.

1 validation
customer_locale
string

The customer’s locale

1 validation
total_ex_tax
string

Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_inc_tax
string

Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_ex_tax
string

The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_inc_tax
string

The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)

1 validation

Responses

Order Response.

1 Example
Schema
object

Order object returned in responses.

$schema: http://json-schema.org/draft-04/schema#
id
integer

Read-only. The ID of the order.

1 validation
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 operation. 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 operation. 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.

1 validation
status
string

The status will include one of the (string, optiona) - 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.

1 validation
subtotal_tax
string

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

1 validation
shipping_cost_tax
string

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

1 validation
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 operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
handling_cost_tax
string

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

1 validation
handling_cost_tax_class_id
integer

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

1 validation
wrapping_cost_tax
string

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

1 validation
wrapping_cost_tax_class_id
integer

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

1 validation
payment_status
string

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

1 validation
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. (Float, Float-As-String, Integer)

1 validation
gift_certificate_amount
string

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

1 validation
currency_id
integer

The display currency ID. May be different from transactional currency. A read-only value. Do not pass in a POST or PUT.

1 validation
currency_code
string

The currency code of the display currency used to present prices on the storefront. A read-only value. Do not pass in a POST or PUT.

1 validation
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. (Float, Float-As-String, Integer)

1 validation
default_currency_id
integer

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

1 validation
coupon_discount
string

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

1 validation
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_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.

1 validation
order_source
string

Orders submitted via the store’s website will include a www value. Orders submitted via the API will be set to external. A read-only value. Do not pass in a POST or PUT.

1 validation
products
object
1 validation
shipping_addresses
object
1 validation
coupons
object
1 validation
status_id
integer

The staus ID of the order.

1 validation
base_handling_cost
string

The value of the base handling cost. (Float, Float-As-String, Integer)

1 validation
base_shipping_cost
string

The value of the base shipping cost. (Float, Float-As-String, Integer)

1 validation
base_wrapping_cost
oneOf

The value of the base wrapping cost. (Float, Float-As-String, Integer)

billing_address
object

Required to create an order.

channel_id
integer

Shows where the order originated. The channel_id will default to 1.

1 validation
customer_id
number
customer_message
string

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

1 validation
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

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

discount_amount
string

Amount of discount for this transaction. (Float, Float-As-String, Integer)

1 validation
ebay_order_id
string

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

1 validation
external_id
oneOf

ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ‘external_id’ cannot be written to. Please remove it from your request before trying again. It can not be overwritten once set.

external_source
oneOf

This value identifies an external system that generated the order and submitted it to BigCommerce via 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.

1 validation
geoip_country_iso2
string

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

1 validation
handling_cost_ex_tax
string

The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_inc_tax
string

The value of the handling cost, including tax. (Float, Float-As-String, Integer)

1 validation
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.

2 validations
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.

2 validations
is_deleted
boolean

Indicates whether the order was deleted (archived). Set to to true, to archive an order.

1 validation
items_shipped
number

The number of items that have been shipped.

1 validation
items_total
number

The total number of items in the order.

1 validation
order_is_digital
boolean

Whether this is an order for digital products.

1 validation
payment_method
string

The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.

1 validation
payment_provider_id
string or number

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

1 validation
refunded_amount
string

The amount refunded from this transaction. (Float, Float-As-String, Integer)

1 validation
shipping_cost_ex_tax
string

The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_inc_tax
string

The value of shipping cost, including tax. (Float, Float-As-String, Integer)

1 validation
staff_notes
string

Any additional notes for staff.

1 validation
subtotal_ex_tax
string

Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_inc_tax
string

Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
tax_provider_id
string

BasicTaxProvider - Tax is set to manual.

AvaTaxProvider - This is for when the tax provider has been set to automatic and the order was NOT created by the API. Used for Avalara.

“” (blank) - When the tax provider is unknown. This includes legacy orders and orders previously created via API. This can be set when creating an order using a POST.

1 validation
customer_locale
string

The customer’s locale

1 validation
total_ex_tax
string

Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_inc_tax
string

Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_ex_tax
string

The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_inc_tax
string

The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)

1 validation

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
order_id
$$.env
1 variable not set
store_hash
X-Auth-Token