post

/orders

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

An order can be created with an existing catalog product or a custom product.

Required Fields

  • products
  • billing_address

Authorization

apiKey - X-Auth-Token

Request Parameters

2 Headers

Request Body

4 Examples
Schema
object

Products and Billing address only required for POST operation.

$schema: http://json-schema.org/draft-04/schema#
products
array[anyOf]
shipping_addresses
array[object]
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)
$$.env
1 variable not set
store_hash
X-Auth-Token