Orders Overview

This article introduces BigCommerce's Orders V2 and Orders V3 REST API resources. Orders V2 exposes endpoints for creating, reading, updating, and deleting orders; it also includes endpoints for managing order shipments and order shipping addresses. Orders V3 surfaces order transactions and order refunds endpoints. For information on processing order payments by API, see Payments API Overview.

Prerequisites:

A BigCommerce store (opens in a new tab)
Access token for API authentication with the following scopes:
- Orders - modify
- Products - read-only
Product with variants.

Creating an order

To create an order, send a POST request to /stores/{{STORE_HASH}}/v2/orders.

Example request: Create an order

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "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
    }
  ]
}

⚠️

Migrating historical orders

When migrating historical orders processed on another eCommerce platform to BigCommerce, supply the code M-MIG for the external_source field. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing.

The example above contains the minimum required fields for a create order request.
The product ordered is a custom product; custom products do not exist in the catalog.
The V2 Orders API will not trigger the typical Order Email (opens in a new tab) 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.

Creating order shipments

Once an order has products, a billing address, and a shipping address, you can create an order shipment.

To create an order shipment, send a POST request to /stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipments.

Example request: Create an order shipment

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}}/v2/orders/{{order_id}}/shipments
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
  "tracking_number": "EJ958083578UK",
  "comments": "Janes Order",
  "order_address_id": "128",
  "shipping_provider": "",
  "items": [
    {
      "order_product_id": 194,
      "quantity": 1
    },
    {
      "order_product_id": 195,
      "quantity": 1
    }
  ]
}

Property	Description
`tracking_number`	Shipping provider tracking number; used to generate tracking link
`comments`	Optional comments
`order_address_id`	Obtain with Get Order Shipping Address
`shipping_provider`	Optional; used to create tracking link; see Create Order Shipment for accepted values
`items.order_product_id`	Obtain with Get Order Products. For non-variant products, use the `id`.

Create multiple shipments by specifying a subset of products and quantities in each POST request.
Create an order shipment with product variants by using the id returned in each GET request.
Creating order shipments triggers email notifications; adjust Order Notification (opens in a new tab) settings in the control panel (opens in a new tab) to change this behavior.
Deleting a shipment does not move the order out of shipped status.

Changing order status

Specify order status by including the status_id property in the create order request. To update an order and change its status, send a PUT request to /v2/orders/{{order_id}}.

Example request: Change order status

PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "status_id": 2
}

To get a list of order statuses, send a GET request to /stores/{{STORE_HASH}}/v2/order_statuses.

Example request: Get order statuses

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/order_statuses
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

If not specified, status_id defaults to 1.
The refunded status is neither paid nor unpaid.
For information on changing custom_label in the control panel, see Order Statuses (opens in a new tab).
When an order is created, set to Awaiting Fulfillment, and then manually edited, inventory levels won't reflect a change in stock. To learn more about inventory stock settings, see Stock Adjustment Settings (opens in a new tab).

Specifying order customer

Specify the customer by including a customer_id in the create order request.

Example request: Specify order customer

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
 
{
  "customer_id": 1,
  "billing_address": {...},
  "products": [...]
}

To get a list of customers, send a GET request to /stores/{{STORE_HASH}}/v3/customers.

Example request: Get a list of customers

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/customers
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Set customer_id to 0 to create a guest order.

Including shipping addresses

Add shipping addresses by including a shipping_address array in the create order request.

Example request: add shipping addresses

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "billing_address": {...},
  "shipping_addresses": [
    {
      "first_name": "Rusty",
      "last_name": "Gates",
      "company": "Example LLC",
      "street_1": "123 Example ST",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "12345",
      "country": "United States",
      "country_iso2": "US",
      "phone": "5128675309",
      "email": "rusty.gates@example.com"
    }
  ],
  "products": [...]
}

Add multiple shipping addresses to ship to multiple locations.

Adding products

Specify products from the catalog by including a products array in a POST request to the Create an order endpoint.

Example request: Add products

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "billing_address": {...},
  "products": [
    {
      "name": "BigCommerce Coffee Mug", # custom product
      "quantity": 1,
      "price_inc_tax": 50,
      "price_ex_tax": 45
    },
    {
      "product_id": 184,               # product from catalog
      "quantity": 1,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "192"
        }
      ]
    }
  ]
}

To get the product_options.id and product_options.value of a product for the order products array, send the following GET request to Get variants by product id. See the example response that follows, or consult the response schema.

Example request: Get product variants

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/variants
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

Custom products do not get added to the catalog.
If the product's price is not specified in the create order request, BigCommerce's pricing service calculates the price by applying applicable currency conversions and pricing operations (such as price lists (opens in a new tab) and customer group discounts (opens in a new tab)) to the product's catalog price; use price_inc_tax and price_ex_tax to override the calculated price.
Marketing promotions currently do not apply to orders created with the Orders API.
If you override price_ex_tax or price_inc_tax, override both; otherwise, order totals will not calculate correctly.
Overriding price_inc_tax or price_ex_tax does not change variant pricing.

Shipping to multiple locations

You can create multiple shipments for orders, and each shipment can have a different order_address_id.

Example 1: order_address_id

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}}/v2/orders/{{order_id}}/shipments
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order_address_id": "123",
  "shipping_provider": "usps",
  "items": [
    {
      "order_product_id": 2,
      "quantity": 1
    }
  ]
}

Property	Description
`order_address_id`	Obtain with Get Order Shipping Address
`shipping_provider`	Optional; used to create tracking link; see Create Order Shipment for accepted values
`items.order_product_id`	Obtain with Get Order Products. For non-variant products, use the `id`.

Getting shipping quotes

To get shipping quotes, send the following GET request. See the example response that follows, or consult the response schema.

Example request: Get shipping quotes

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipping_addresses/{{shipping_address_id}}/shipping_quotes
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Generating a quote through a shipping carrier is not supported. You can specify a shipping carrier when creating an order shipment. You can generate the quote elsewhere, then update the shipping_cost_ex_tax and shipping_cost_inc_tax for the order total to be correct.

Getting order taxes

To get order taxes, send the following GET request. See the example response that follows, or consult the response schema.

Example request: Get order taxes

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/taxes
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

The response's order tax object name property gets set to API Tax Override when generated by third-party tax services like Avalara Premium (opens in a new tab).

Example response detail: Tax object from get order taxes

[
  {
    "id": 13,
    "order_id": 138,
    "order_address_id": 39,
    "tax_rate_id": 1,
    "tax_class_id": 0,
    "name": "API Tax Override",
    ...
  }
]

BigCommerce submits tax documents to Avalara when an order moves from an unpaid status to a paid status and voids tax documents when an order moves from a paid status to an unpaid status.

Existing Status	Status Passed	Resultant Status	Avalara Tax Document Submission
Any	None	`Pending`	None
Paid or `Refunded`	Paid	Paid	None
Unpaid or `Refunded`	Unpaid	Unpaid	None
Paid or `Refunded`	Unpaid	Unpaid	Tax document voided
Unpaid or `Refunded`	Paid	Paid	Tax document submitted

Abbreviated state names (ex: CA instead of California) in an order address will cause tax document submission to fail.
You can calculate taxes using rules specified in the store unless automatic taxes (opens in a new tab) are enabled.
You can optionally override tax values by specifying price_inc_tax and price_ex_tax in an update order request.
If a store has automatic tax (opens in a new tab) enabled, BigCommerce does not compute sales tax on orders created with the API.

Getting order transactions

To get order transactions, send the following GET request. See the example response that follows, or consult the response schema.

Example request: Get order transactions

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{{order_id}}/transactions
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Not all payment gateways return the full card or fraud detail. Depending on the payment method, different information will be available.

Handling refunds

Orders V3 exposes endpoints for managing order refunds. For an overview on using these endpoints, see Order Refunds in API Docs.

Calculating totals

Order subtotal and total calculate automatically; edits to the following properties trigger a recalculation.

Property	Type	Description
`products`	`array[obj]`	Used to calculate shipping, taxes, and subtotal
`shipping_cost_ex_tax`	`float`	Shipping cost, excluding tax
`shipping_cost_inc_tax`	`float`	Shipping cost, including tax
`handling_cost_ex_tax`	`float`	Value of handling cost, excluding tax
`handling_cost_inc_tax`	`float`	Value of handling cost, including tax
`wrapping_cost_ex_tax`	`float`	Value of wrapping cost, excluding tax
`wrapping_cost_inc_tax`	`float`	Value of wrapping cost, including tax
`billing_address`	`obj`	Used to calculate shipping and taxes
`shipping_addresses`	`array[obj]`	Used to calculate shipping and taxes

You can override calculated values such as product prices, subtotals, and totals by sending a fixed value in the request. If you do not supply values for these properties, you will automatically calculate them based on the preset store values and tax rules.

If you override subtotal or total, override both; the system will not re-calculate the other.
To add a manual discount, overwrite the product price or discount_amount.

FAQ

Is adding coupons available?

Coupon redemption is unavailable. You can not write to the coupon_discount field. You can add a discount to the order by using the discount_amount.

How do I create an order for a guest?

To specify a guest checkout, set customer_id to 0.

How do I set the order source?

You cannot specify the order_source; its value is external. You can optionally specify a value for external_source to define which external source the order is coming from - e.g., POS system X, accounting system Y, etc.

Note: To publish an app that creates orders, it must include the external_source field on new orders, with the app's ID as the value. See App Store Approval Requirements to learn more.

Can I create an order with only custom products?

Yes, the store's catalog does not include products.

What is the difference between country_ISO2 and country?

There is no requirement to specify country when you specify country_ISO2 in the shipping and billing addresses and vice versa.

How can I take payment for an order?

You can either process payment through a third party or using the control panel.

Can I generate a shipping quote from a carrier using the API?

Not at this time. If you create an order either in the control panel or by API, it will return a 204 when trying to get a shipping quote.

Related resources

Articles

Endpoints

Webhooks

Orders

Did you find what you were looking for?

Tax customers Refunds