beehexa bigcommerce api how to create retrieve and update an order

BigCommerce API 2024: How To Create, Retrieve And Update An Order

Overview

Beehexa will show you how to work with BigCommerce API to create, retrieve and update an order using Postman in this article. Following this process, you can create, retrieve and update an order with all the information you want using Postman.

In detail BigCommerce Order API overview Orders V2 exposes endpoints for creating, reading, and updating orders and includes endpoints for managing order coupons, messages, products, shipping addresses, statuses, taxes, shipments, and shipping address quotes.

There are prerequisites:

  • A BigCommerce store
  • Access token for API authentication with the following scopes:
    • Orders – modify
    • Products – read-only
  • Product with variants.

As I have noted, here are the steps you have to do to check the scope: 

  • Firstly, go to the Home page
  • Secondly, select “Account settings section
  • Then roll down to API to click on API account to check the scope
BigCommerce API: Checking Scope
beehexa 13

BigCommerce Order API: Create an Order

We will create an order in BigCommerce using Postman.

So, log in Postman account and then choose a workspace

After that, we are ready to create an order using Postman.

At first, select POST and paste the URL:

https://api.bigcommerce.com/stores/{store_hash}/v2/orders

Accordingly, Replace {store_hash} with your store_hash generated on BigCommerce from the API path.

  1. In the Header section, you need to declare the information :
  • Accept : application/json
  • Content-Type : application/json
  • X-Auth-Token: Access token
BigCommerce API: How to create an order
beehexa 132 1
  1. In the Body section

After that, click on “raw” to fill in the data; remember to change the “text” to “JSON.”

Once again, remember an order can be created with an existing catalog product or a custom product.

Required Fields:

  • Products
    • Name Alias for name_customer. The product name that is shown to customers in the storefront.
    • Quantity: number
    • Price_ex_tax : Number
    • Price_inc_tax : Number
  • Billing_address

For example, I will show you our example code below, and you can create your order

{
  "billing_address": {
    "first_name": "Chau",
    "last_name": "Hoang",
    "street_1": "123 Main Street",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "email": "ngan.chau@beehexa.com"
  },
  "products": [
    {
      "name": "Bunny doll",
      "quantity": 1,
      "price_inc_tax": 10,
      "price_ex_tax": 15
    }
  ]
}
Code language: JSON / JSON with Comments (json)

Note

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

Finally, the API will return the data like this.  

{
    "id": 103,
    "customer_id": 0,
    "date_created": "Fri, 30 Sep 2022 08:23:54 +0000",
    "date_modified": "Fri, 30 Sep 2022 08:23:54 +0000",
    "date_shipped": "",
    "status_id": 1,
    "status": "Pending",
    "subtotal_ex_tax": "15.0000",
    "subtotal_inc_tax": "10.0000",
    "subtotal_tax": "-5.0000",
    "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": "15.0000",
    "total_inc_tax": "10.0000",
    "total_tax": "-5.0000",
    "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": "",
    "ip_address_v6": "",
    "geoip_country": "",
    "geoip_country_iso2": "",
    "currency_id": 1,
    "currency_code": "VND",
    "currency_exchange_rate": "1.0000000000",
    "default_currency_id": 1,
    "default_currency_code": "VND",
    "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": "Chau",
        "last_name": "Hoang",
        "company": "",
        "street_1": "123 Main Street",
        "street_2": "",
        "city": "Austin",
        "state": "Texas",
        "zip": "78751",
        "country": "United States",
        "country_iso2": "US",
        "phone": "",
        "email": "ngan.chau@beehexa.com",
        "form_fields": []
    },
    "is_email_opt_in": false,
    "credit_card_type": null,
    "order_source": "external",
    "channel_id": 1,
    "external_source": null,
    "products": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/products",
        "resource": "/orders/102/products"
    },
    "shipping_addresses": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/shipping_addresses",
        "resource": "/orders/102/shipping_addresses"
    },
    "coupons": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/coupons",
        "resource": "/orders/102/coupons"
    },
    "external_id": null,
    "external_merchant_id": null,
    "tax_provider_id": "",
    "customer_locale": "",
    "external_order_id": "",
    "store_default_currency_code": "VND",
    "store_default_to_transactional_exchange_rate": "1.0000000000",
    "custom_status": "Pending"
}
Code language: JSON / JSON with Comments (json)

BigCommerce Order API: Retrieve an Order

Create a new request and select GET, then paste the URL below : https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{order_id}

Then, replace {store_hash} with your store_hash generated on BigCommerce from the API path.

Replace {order_id} with the order ID you have just created before

Afterward, in the Header section, you need to declare the information:

  • Accept : application/json
  • Content-Type : application/json
  • X-Auth-Token: Access token
BigCommerce API: How to retrieve an order
beehexa BigCommerce Order API: Retrieve an Order

Then click send to call the API.

As a result, the API will return the data of the order.

{
    "id": 102,
    "customer_id": 0,
    "date_created": "Fri, 30 Sep 2022 08:23:54 +0000",
    "date_modified": "Fri, 30 Sep 2022 08:23:54 +0000",
    "date_shipped": "",
    "status_id": 1,
    "status": "Pending",
    "subtotal_ex_tax": "15.0000",
    "subtotal_inc_tax": "10.0000",
    "subtotal_tax": "-5.0000",
    "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": "15.0000",
    "total_inc_tax": "10.0000",
    "total_tax": "-5.0000",
    "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": "",
    "ip_address_v6": "",
    "geoip_country": "",
    "geoip_country_iso2": "",
    "currency_id": 1,
    "currency_code": "VND",
    "currency_exchange_rate": "1.0000000000",
    "default_currency_id": 1,
    "default_currency_code": "VND",
    "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": "Chau",
        "last_name": "Hoang",
        "company": "",
        "street_1": "123 Main Street",
        "street_2": "",
        "city": "Austin",
        "state": "Texas",
        "zip": "78751",
        "country": "United States",
        "country_iso2": "US",
        "phone": "",
        "email": "ngan.chau@beehexa.com",
        "form_fields": []
    },
    "is_email_opt_in": false,
    "credit_card_type": null,
    "order_source": "external",
    "channel_id": 1,
    "external_source": null,
    "products": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/products",
        "resource": "/orders/102/products"
    },
    "shipping_addresses": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/shipping_addresses",
        "resource": "/orders/102/shipping_addresses"
    },
    "coupons": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/coupons",
        "resource": "/orders/102/coupons"
    },
    "external_id": null,
    "external_merchant_id": null,
    "tax_provider_id": "",
    "customer_locale": "",
    "external_order_id": "",
    "store_default_currency_code": "VND",
    "store_default_to_transactional_exchange_rate": "1.0000000000",
    "custom_status": "Pending"
}
Code language: JSON / JSON with Comments (json)

BigCommerce Order API: Update an Order

First of all, to add a product or more to an existing order, don’t include the id in the body. Include product_options if adding a product with variants.

In order to update a product, include the id in the body of the order. In the body, only the fields that need to be updated should be included. Fields that are omitted will not be changed.

Usage notes

To add a product to an existing order, don’t include id in the payload. When adding a product with variants, product_options are required. To update an order product line, it is necessary to provide an ID. The payload should only contain the fields that need to be updated. If you omit any fields, they will remain unchanged.

Note the following constraints and default field values:

  • xxx and xxx_customer always hold the same value. Updating either xxx or xxx_customer will change the value of both fields.
  • If both fields xxx and xxx_customer are present, they must have the same value.
  • Empty strings ” and null are invalid for xxx, xxx_customer, and xxx_merchant.
  • When updating an existing order product without changing the variant, product, or product options, requests that do not contain xxx_merchant will fail.
  • When updating an existing order product, requests that do not contain both fields xxx and xxx_customer will fail.
  • Empty strings ” and null are invalid for xxx, xxx_customer, and xxx_merchant. If xxx_merchant` is omitted, it will default to have the catalog value.
  • If both fields xxx and xxx_customer are omitted from the request, they will default to the catalog value.

Create a new request and select PUT, then paste the URL below :

Then, replace {store_hash} with your store_hash generated on BigCommerce from the API path.

Replace {order_id} with the order ID you have just created before

  1. In the Header section, you need to declare the information:
  • Accept : application/json
  • Content-Type : application/json
  • X-Auth-Token: Access token
BigCommerce API: How to Update an order
beehexa 136

2. In the Body section

Likewise, click on “raw” to fill in the data; remember to change the “text” to “JSON.”

For example, I will show you our example code below, and you can update your order

{
 "status_id": 1,
 "customer_id": 0,
 "billing_address": {
   "first_name": "Chau",
   "last_name": "Hoang",
   "street_1": "123 Main Street",
   "city": "Austin",
   "state": "Texas",
   "zip": "78751",
   "country": "United States",
   "country_iso2": "US",
   "email": "Ngan.chau@beehexa.com"
 },
 "shipping_addresses": [
   {
     "first_name": "Trish",
     "last_name": "Test",
     "company": "Acme Pty Ltd",
     "street_1": "666 Sussex St",
     "city": "Austin",
     "state": "Texas",
     "zip": "78751",
     "country": "United States",
     "country_iso2": "US",
     "email": "elsie@gmail.com"
   }
 ],
 "products": [
   {
     "name": "Teddy bear",
     "quantity": 2,
     "price_inc_tax": 10,
     "price_ex_tax": 10
   },
   {
     "name": "Bunny Doll",
     "quantity": 1,
     "price_inc_tax": 10,
     "price_ex_tax": 15
   }
 ],
 "customer_locale": "en"
}
Code language: JSON / JSON with Comments (json)

As a result, the API will return the update data about the update order

{
    "id": 102,
    "customer_id": 0,
    "date_created": "Fri, 30 Sep 2022 08:23:54 +0000",
    "date_modified": "Fri, 30 Sep 2022 08:38:44 +0000",
    "date_shipped": "",
    "status_id": 1,
    "status": "Pending",
    "subtotal_ex_tax": "50.0000",
    "subtotal_inc_tax": "40.0000",
    "subtotal_tax": "-10.0000",
    "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": "50.0000",
    "total_inc_tax": "40.0000",
    "total_tax": "-10.0000",
    "items_total": 4,
    "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": "",
    "ip_address_v6": "",
    "geoip_country": "",
    "geoip_country_iso2": "",
    "currency_id": 1,
    "currency_code": "VND",
    "currency_exchange_rate": "1.0000000000",
    "default_currency_id": 1,
    "default_currency_code": "VND",
    "staff_notes": null,
    "customer_message": null,
    "discount_amount": "0.0000",
    "coupon_discount": "0.0000",
    "shipping_address_count": 2,
    "is_deleted": false,
    "ebay_order_id": "0",
    "cart_id": null,
    "billing_address": {
        "first_name": "Chau",
        "last_name": "Hoang",
        "company": "",
        "street_1": "123 Main Street",
        "street_2": "",
        "city": "Austin",
        "state": "Texas",
        "zip": "78751",
        "country": "United States",
        "country_iso2": "US",
        "phone": "",
        "email": "Ngan.chau@beehexa.com",
        "form_fields": []
    },
    "is_email_opt_in": false,
    "credit_card_type": null,
    "order_source": "external",
    "channel_id": 1,
    "external_source": null,
    "products": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/products",
        "resource": "/orders/102/products"
    },
    "shipping_addresses": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/shipping_addresses",
        "resource": "/orders/102/shipping_addresses"
    },
    "coupons": {
        "url": "https://api.bigcommerce.com/stores/q851icihwa/v2/orders/102/coupons",
        "resource": "/orders/102/coupons"
    },
    "external_id": null,
    "external_merchant_id": null,
    "tax_provider_id": "",
    "customer_locale": "en",
    "external_order_id": "",
    "store_default_currency_code": "VND",
    "store_default_to_transactional_exchange_rate": "1.0000000000",
    "custom_status": "Pending"
}

Code language: JSON / JSON with Comments (json)

In conclusion, the above are all steps to update a channel on BigCommerce with Postman. Please comment below or refer to our BigCommerce API documentation if you have any questions.

Finally, I hope you can achieve it!

In the video below, you will see these steps visually: