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 via API, see Payments API Overview.

Prerequisites:

• A BigCommerce store
• Access token for API authentication with the following scopes:
  • Orders - Modify
  • Products - Read
• Product with variants.

Creating an order

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

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
    }
  ]
}

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

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.

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

Response:

[
  {
    "id": 0,
    "name": "Incomplete",
    "system_label": "Incomplete",
    "custom_label": "Incomplete - Testing",
    "system_description": "An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.",
    "order": 0
  },
  ...
]

Specifying order customer

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

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.

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

Including shipping addresses

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

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": [...]
}

Adding products

Specify products from the catalog by including a products array in the create order request.

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 a GET request to /stores/{{STORE_HASH}}/v3/catalog/products/{product_id}/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

Response:

{
  "data": [
    {
      "id": 421,
      "product_id": 184,
      ...
      "option_values": [
        {
          "id": 180,         // product_options.value
          "label": "Red",
          "option_id": 200,  // product_options.id
          "option_display_name": "Color"
        },
        {
          "id": 192,
          "label": "Small",
          "option_id": 230,
          "option_display_name": "T-Shirt Size"
        }
      ]
    }
    ...
  ]
}

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.

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	Obtainable via Get Order Shipping Address
shipping_provider	Optional; used to create tracking link; see Create Order Shipment for accepted values
items.order_product_id	Obtainable via Get Order Products

Shipping to multiple locations

You can create multiple shipments for orders, and each shipment can have a different 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
    }
  ]
}

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": "456",
  "shipping_provider": "",
  "items": [
    {
      "order_product_id": 5,
      "quantity": 1
    }
  ]
}

Property	Description
order_address_id	Obtainable via Get Order Shipping Address
shipping_provider	Optional; used to create tracking link; see Create Order Shipment for accepted values
items.order_product_id	Obtainable via Get Order Products

Getting shipping quotes

To get shipping quotes, send a GET request to /v2/orders/{order_id}/shipping_addresses/{shipping_address_id}/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

Response:

{
  "id": "16",
  "uuid": "18aaa5eb-3c7a-4bf8-bfaa-d14d155606f1",
  "timestamp": "Mon, 30 Jul 2018 15:32:35 +0000",
  "shipping_provider_id": "bcproductbased",
  "shipping_provider_quote": [],
  "provider_code": "productfixedshipping",
  "carrier_code": "",
  "rate_code": "",
  "rate_id": ""
}

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 a GET request to /stores/{{STORE_HASH}}/v2/orders/{order_id}/taxes.

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

Response:

[
  {
    "id": 13,
    "order_id": 138,
    "order_address_id": 39,
    "tax_rate_id": 1,
    "tax_class_id": 0,
    "name": "Tax",
    "class": "Default Tax Class",
    "rate": "8.0000",
    "priority": 0,
    "priority_amount": "17.6400",
    "line_amount": "17.6400"
  }
]

The response’s order tax object name property gets set to API Tax Override when generated by third-party tax services like Avalara Premium.

[
  {
    "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

Getting order transactions

To get order transactions, send a GET request to /stores/{{STORE_HASH}}/v3/orders/{order_id}/transactions.

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

Response:

{
  "data": [
    {
      "id": 85926313,
      "order_id": "121",
      "event": "purchase",
      "method": "nonce",
      "amount": 1,
      "currency": "USD",
      "gateway": "squarev2",
      "gateway_transaction_id": "pN5Kd7R9ilEI2ygBawCy7tMF|qwnAFAxRZ7tYRtIpZULg1yMF",
      "status": "ok",
      "test": false,
      "fraud_review": false,
      "reference_transaction_id": {},
      "date_created": "2018-05-08T15:06:12+00:00",
      "avs_result": {...},
      "cvv_result": {...},
      "credit_card": {},
      "gift_certificate": {},
      "store_credit": {},
      "offline": {},
      "custom": {},
      "payment_instrument_token": {},
      "payment_method_id": "squarev2.card"
    }
  ],
  "meta": {...}
}

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.

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.

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 via API, it will return a 204 when trying to get a shipping quote.

Related resources

Articles

• Payments API Overview
• Order Refunds
• Order Statuses
• Order Notifications

Endpoints

• Storefront Orders
• Orders v2
• Orders v3

Webhooks

• Orders