Orders API Guide

An order can be created using the /orders endpoint. It requires a list of products and a billing address for a valid order.

This endpoint will accept existing products or custom products created using the products array. Custom products are not added to the existing store’s catalog.


Create an Order

POST /v2/orders

At a minimum, an order needs products and billing addresses.

For this example, we will create an order using a custom product, existing store product and add a billing address.

Create a custom product

  • name: Product Name
  • quantity: Number of items
  • price_inc_tax: Price including tax
  • price_ex_tax: Price excluding tax

Creating a custom product does not add it to the catalog. Only to the current order

Create Custom Product
{
  "name": "BigCommerce Poster",
  "quantity": 1,
  "price_inc_tax": 10.98,
  "price_ex_tax": 10
}

Add an Existing Product with Options

To add an existing product with options, first, make a request to https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/variants

Make note of the option_values > id and option_values > option_id. These will be passed into the products array.

Example /GET Variants Response
https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/variants
{
    "data": [
        {
            "id": 421,
            "product_id": 184,
            "sku": "RED",
            "sku_id": 383,
            "price": null,
            "calculated_price": 249,
            "sale_price": null,
            "retail_price": null,
            "map_price": null,
            "weight": null,
            "calculated_weight": 15,
            "width": null,
            "height": null,
            "depth": null,
            "is_free_shipping": false,
            "fixed_cost_shipping_price": null,
            "purchasing_disabled": false,
            "purchasing_disabled_message": "",
            "image_url": "",
            "cost_price": 0,
            "upc": "",
            "mpn": "",
            "gtin": "",
            "inventory_level": 0,
            "inventory_warning_level": 0,
            "bin_picking_number": "",
            "option_values": [
                {
                    "id": 180,
                    "label": "Red",
                    "option_id": 200,
                    "option_display_name": "Color"
                },
                {
                    "id": 192,
                    "label": "Small",
                    "option_id": 230,
                    "option_display_name": "T-Shirt Size"
                }
            ]
        }
...

Then create the products array which includes the custom product and the existing product with product options. Using the option_id and option_value id from the previous request we can build the products array.

product_options > id = option_values > option_id

product_options > value = option_values > id

The product_options > value must be passed in as a string.

Example Products Array
"products":[
          {
              "name": "BigCommerce Poster",
              "quantity": 1,
              "price_inc_tax": 10.98,
              "price_ex_tax": 10.00
          },
          {
              "product_id": 184,
                "product_options":[
                    {
                        "id": 200,
                        "value": "180"
                    },
                    {
                        "id": 230,
                        "value": "192"
                    }
                ]

          }
      ]
Try it Now
Create an Order
Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
store_hash

The response will have abbreviated order contents with sub-resources available to get the full order information. The order is automatically set to a status of 1 or Pending. It also returns an id which is the order id. In the example below, the order id is 193.

  • The order products sub-resource will list the products added.
  • The shipping_addresses sub-resource will have the shipping addresses.
  • The coupons sub-resource will have any coupons added to the order.
Create Order Response
{
  "id": 193,
  "customer_id": 0,
  "date_created": "Fri, 12 Oct 2018 19:06:23 +0000",
  "date_modified": "Fri, 12 Oct 2018 19:06:23 +0000",
  "date_shipped": "",
  "status_id": 1,
  "status": "Pending",
  "subtotal_ex_tax": "10.0000",
  "subtotal_inc_tax": "10.9800",
  "subtotal_tax": "0.9800",
  "base_shipping_cost": "0.0000",
  "shipping_cost_ex_tax": "0.0000",
  "shipping_cost_inc_tax": "0.0000",
  "shipping_cost_tax": "0.0000",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "10.0000",
  "total_inc_tax": "10.9800",
  "total_tax": "0.9800",
  "items_total": 1,
  "items_shipped": 0,
  "payment_method": "Manual",
  "payment_provider_id": null,
  "payment_status": "",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": null,
  "customer_message": null,
  "discount_amount": "0.0000",
  "coupon_discount": "0.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": "0",
  "cart_id": null,
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "123 Main Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "janedoe@email.com",
    "form_fields": []
  },
  "is_email_opt_in": false,
  "credit_card_type": null,
  "order_source": "external",
  "external_source": null,
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/products",
    "resource": "/orders/193/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/shippingaddresses",
    "resource": "/orders/193/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/coupons",
    "resource": "/orders/193/coupons"
  },
  "external_id": null,
  "external_merchant_id": null,
  "custom_status": "Pending"
}

Update an Order

In the update, we are going to change the order status, customer_id and add an existing store product.

Order Status

The order status is currently set to "status": "Pending". This is the default status for orders made using the API. To change this, the status_id needs to be updated with the corresponding id. In this example the status is set to 7 or Awaiting Payment.

For a full list of order statuses see Order Status endpoint.

Customer

The customer_id is set to 0. This is the default for orders created using the API. For a list of available customers in the store use the Customers Endpoint.

Add a Product

An existing store product or a new custom product can be added during a /PUT request. The products must be added as an array of objects. To get a list of store products use the Catalog Products endpoint.

{
	"products":[
		{
			"product_id": 196,
			"quantity": 1

		}
	]
}

The shipping address cannot be updated or set using the API. It will default to the billing address.

Try it Now
Update an Order
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
Example Order Response
{
  "id": 193,
  "customer_id": 13,
  "date_created": "Fri, 12 Oct 2018 19:06:23 +0000",
  "date_modified": "Tue, 16 Oct 2018 17:05:30 +0000",
  "date_shipped": "",
  "status_id": 7,
  "status": "Awaiting Payment",
  "subtotal_ex_tax": "35.9900",
  "subtotal_inc_tax": "41.2500",
  "subtotal_tax": "5.2600",
  "base_shipping_cost": "0.0000",
  "shipping_cost_ex_tax": "0.0000",
  "shipping_cost_inc_tax": "0.0000",
  "shipping_cost_tax": "0.0000",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "35.9900",
  "total_inc_tax": "40.2700",
  "total_tax": "4.2800",
  "items_total": 2,
  "items_shipped": 0,
  "payment_method": "Manual",
  "payment_provider_id": null,
  "payment_status": "",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": null,
  "customer_message": null,
  "discount_amount": "0.0000",
  "coupon_discount": "0.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "ebay_order_id": "0",
  "cart_id": null,
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "street_1": "123 Main Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "janedoe@email.com",
    "form_fields": []
  },
  "is_email_opt_in": false,
  "credit_card_type": null,
  "order_source": "external",
  "external_source": null,
  "products": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/products",
    "resource": "/orders/193/products"
  },
  "shipping_addresses": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/shippingaddresses",
    "resource": "/orders/193/shippingaddresses"
  },
  "coupons": {
    "url": "https://api.bigcommerce.com/stores/{store_hash}/v2/orders/193/coupons",
    "resource": "/orders/193/coupons"
  },
  "external_id": null,
  "external_merchant_id": null,
  "custom_status": "Awaiting Payment"
}

Next Steps

  • Try updating the billing_address
  • Review the Orders API