How to Use BigCommerce Order Api?
Last updated: June 20 2021
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 API includes 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 POST
request 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.