Skip to navigation
RESTAdminManagementOrders

Create Order

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 consignments object lets you create a pickup consignment. Inventory for the pickup consignment’s line items is checked and deducted at the location assigned to the pickup_method_id, which can be any inventory location, not only the default location. Orders created with products and shipping_addresses always deduct inventory from the default location.

  • An order can have either a pickup or a shipping fulfillment method, but not both.
  • An order can have only one pickup consignment.
  • To create a pickup consignment, the target location must have a pickup method assigned to it. See the Pickup Methods API.

To create a pickup order server-side, for example from a marketplace or point-of-sale (POS) import, send consignments.pickups instead of products and shipping_addresses. See the Order with pickup method request example.

Choose from one of the following:

  1. Create order with a shipping fulfillment method using shipping_addresses and products
  2. Create order with a pickup fulfillment method using consignments. Inventory is deducted at the pickup method’s location.

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 shipping_addresses and products can’t be present, and vice versa.

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.

If you are building an app that creates orders, it must include your app’s ID in the external_source field of new orders to be approved for the App Marketplace. See App Store Approval Requirements to learn more.

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

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

default_currency_codestringOptional

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

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

productslist of objectsOptional
refunded_amountstringOptional

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

shipping_addresseslist of objectsOptional
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)

staff_notesstringOptional<=65535 characters
Any additional notes for staff.
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)

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)

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)

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.