How to Use BigCommerce Order Api?

Considered as a bridge, API (or Application Programming Interface) is an important part that connects two applications and makes them work well with each other. Recently, API has demonstrated its status and has been used in multiple platforms, including BigCommerce.

Understanding the advantages of API, BigCommerce introduces to its users’ Order API, Storefront API, and Catalog API. However, in this post, we only concentrate on Order API, which access order data with a view to enhancing POS and fulfillment in your BigCommerce store.

In BigCommerce Order API, there are two resources which are Order V2 and Order V3. Each of them is responsible for different tasks. While Order V2 is used for reading, creating, updating, deleting orders, and managing order shipments and order shipping addresses, the functions of Order V3 are for order transactions and order refunds.

In this post, we would like to provide you with some requests for the BigCommerce Order API that all stores have to use, so don’t miss it!

Before having a look at the request, please remember to fill in your data in the “…” symbol.

How to create an order?

Send a POST request to /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”: “…”,`

` “last_name”: “…”,`

` “street_1”: “…”,`

` “city”: “…”,`

` “state”: “…”,`

` “zip”: “…”,`

` “country”: “…”,`

` “country_iso2”: “US”,`

` “email”: “…”`

` },`

` “products”: [`

` {`

` “name”: “…”,`

` “quantity”: …,`

` “price_inc_tax”: …,`

` “price_ex_tax”: …`

` }`

` ]`

}

The code above includes the minimum fields that are needed to create an order of custom product via API

How to change the status of an order?

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”: …`

}

If the status id is not specified, you can choose the default number which is 1.

How to add shipping addresses?

Send a POST request to /v2/orders/{order_id}/shipping_addresses/{id}:

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”: “…”,`

` “last_name”: “…”,`

` “company”: “…”,`

` “street_1”: “…”,`

` “street_2”: “”,`

` “city”: “…”,`

` “state”: “…”,`

` “zip”: “…”,`

` “country”: “…”,`

` “country_iso2”: “..”,`

` “phone”: “…”,`

` “email”: “…”`

` }`

` ],`

` “products”: […]`

}

How to generate order shipment?

Send a POST request to /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”: “…”,`

` “comments”: “…”,`

` “order_address_id”: “…”,`

` “shipping_provider”: “”,`

` “items”: [`

` {`

` “order_product_id”: …,`

` “quantity”: …`

` },`

` {`

` “order_product_id”: …,`

` “quantity”: …`

` }`

` ]`

}

The comments and shipping_provider fields are optional, so you can decide not to fill in the data. With the id of order address and order product, you can find out its id by using the GET request.

How to ship orders to multiple places?

Send a POSTrequest to /v2/orders/{{order_id}}/shipments, users can create a request allowing them to ship the same orders to multiple addresses.

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”: “…”,`

` “shipping_provider”: “…”,`

` “items”: [`

` {`

` “order_product_id”: …,`

` “quantity”: …`

` }`

` ]`

}

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”: “…”,`

` “shipping_provider”: “”,`

` “items”: [`

` {`

` “order_product_id”: …,`

` “quantity”: …`

` }`

` ]`

}

Keep in mind that the order_address_id fields are different from each other.

How to get order taxes?

Send a GET request to /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

And the response will be like:

[

` {`

` “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”`

` }`

]

Users are offered two options to get order taxes which are using the built-in feature in BigCommerce or integrating with third-party tax services. In BigCommerce, the name in the response is Tax. However, when integrating with a platform as Avalara AvaTax, it will turn to API Tax Override. In addition, Avalara will receive tax documents from BigCommerce when the order status moves from unpaid to paid. Otherwise, the tax documents will be voided.

Furthermore, you shouldn’t use the abbreviation in the order address since it can make it impossible to submit the tax document. Also, you can make use of your own rules or enable automatic taxes to calculate taxes. When allowing automated taxes, the sale taxes on orders generated via the API will not be calculated.

How to get order transactions?

Send a GET request to /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

And, the response will be like:

{

` “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”: {…}`

}

There are three payment methods for creating order transactions, which are Test Payment Gateway, PayPal Express, and Amazon Pay. In fact, based on the payment methods, the data returned will be different; some return all details of card or fraud, and some don’t.

Final thoughts

Overall, it is inevitable that exploiting API in BigCommerce can bring users numerous benefits. However, you need to have a certain base of technology to use it effectively. Above are the most frequent tasks of using BigCommerce order API that can be conducted via the API. Hope that you can leverage it for your store management.