NAV

Quickstart Guides for Developing on BigCommerce

The BigCommerce ecommerce platform provides a flexible API, enabling you to create technical solutions for businesses in the language of your choice.

We believe starting development on our platform should be easy. Whether or not you have built with APIs or used our templating engine before, we want you to have the tools to start your project efficiently.

cURL Quickstart Guide

This section provides some sample cURL commands, for quickstart purposes. These use Basic Authentication, so before you can issue these commands, you must generate Basic Authentication credentials by following the steps discussed here. Once you have your Basic Authentication credentials, you can issue cURL commands as listed below.

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/time

If the request is made using the Authorization header, you need to encode the credentials using base64. Or, a simple way to accomplish the same task as above is:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json

Orders cURL Commands

Here are sample cURL commands to handle orders.

Get a List of Orders from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json

By default, the API request returns only 50 orders. If you want to return all the orders from the store, you must use filters, as shown in the next example below.

Get All Orders from the Store

Use the limit and page filter parameters to get a data beyond what the default query returns. Note that 200 orders is the maximum returned per page:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/orders.json?limit=200&page=1

Update an Order

Orders take many fields upon update requests. (For details, please see this documentation.) Here, we update an order using just the mandatory fields:

    curl --request PUT \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    --data-binary '{"status_id":1}' \
    https://store.mybigcommerce.com/api/v2/orders/101

Get Orders Created since a Certain Date

You can use the If-Modified-Since header to request orders that have been created after a given date:

    curl -I --request GET \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    -H "If-Modified-Since: Tue, 4 Dec 2012 00:00:00 GMT" \
    https://store.mybigcommerce.com/api/v2/orders.json

Get Coupons Associated with an Order

An order can contain coupons, which might be applied to the order to offer discounts to the customer. You can look at all the available coupons in an order as follows:

    curl --request GET \
    -u "_username_:_API_key_"\
    https://store.mybigcommerce.com/api/v2/orders/115/coupons.json

Create a Shipment for an Order

You can create a shipment for an order via the Orders > Create a Shipment endpoint. As an example, third-party shipping services can query orders from a store when the orders are created, and create shipments for those:

    curl --request POST \
    -u "_username_:_API_key_" \
    -H "Content-Type: application/json" \
    -d '{"order_address_id":15,"tracking_number":"123-123-123","items":[{"order_product_id":15,"quantity":1}]}' \
    https://store.mybigcommerce.com/api/v2/orders/114/shipments.json

Products cURL Commands

Here are sample cURL commands to handle products.

Get a List of Products from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products.json

By default, the API request returns only 50 products. If you want to return all the products from the store, you must use filters, as shown in the example below.

Get All Products from the Store

Use the limit and page filter parameters to get data beyond what the default query returns. Note that a maximum of 200 products are returned per page:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products.json?limit=200&page=1

Create a Product

Products have many fields. For details on the product fields allowed as part of a POST request, please see this page.

Let’s assume that we want to create a product using only the fields that are for a POST request. Here, price must specified as a string, while weight is a decimal. The is_visible flag is not mandatory, but if it is not set to true, the product would not be visible by default:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"startrek","price":19.99,"categories":[2],"type":"physical","availability":"available", "weight":0}' \
    https://store.mybigcommerce.com/api/v2/products.json

Update a Product

To update the product created above, you could use the following:

    curl --request PUT \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"startrek","sku":"STREK-DVD","categories":[2,3],"inventory_tracking":"simple","inventory_level":"500", "inventory_warning":100}' \
    https://store.mybigcommerce.com/api/v2/products/id.json

Search a Product by SKU

To search by a product SKU, we could use the following code. Remember that when a product has optionset/variations defined, and if the individual options have SKUs defined, then the product SKU is overriden by the option SKUs. Currently, there are two ways to search for SKUs: GET /products?sku="something" or GET /products/skus?sku="something". The first call returns only product-level SKUs and not option-level SKUs.

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/products/skus.json?sku="abcd"

Coupons cURL Commands

Here are sample cURL commands to handle coupons.

Get a List of Coupons from the Store

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/coupons.json

Coupons can be filtered by code, type, name, min_id and max_id. Without these filters, the call returns all the coupons in the store. So for example, if we wanted to return a list of only those coupons of type=percentage_discount, we could make the following request:

    curl --request GET \
    -u "_username_:_API_key_" \
    https://store.mybigcommerce.com/api/v2/coupons.json?type=percentage_discount

For details on filter fields, please see the Coupons resource.

Create a Coupon

Coupons can be created by a POST request on the coupons endpoint. For example, if we want to create a coupon to take 50% off an order, then our coupon will have percentage_discount as the type. The applies_to field is optional, and can be used to restrict the coupon to a set of products or categories. In the example shown below, the coupon is being restricted to a set of products:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"code":"50OFF", "type":"percentage_discount", "name":"testcoupon1", "amount":50.00, "enabled":"true", "applies_to":"{\"entity\":\"products\",\"ids\":[32]}"}' \
    https://store.mybigcommerce.com/api/v2/coupons.json

Update a Coupon

Updating a coupon is almost similar to the Create example above, except that we work off an ID via a PUT request. For example, assume that we want to change the above coupon from a 50% to a 30% discount, and that the coupon ID is 15. We can update the coupon using the following:

    curl --request PUT \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"code":"30OFF", "type":"percentage_discount"' \
    https://store.mybigcommerce.com/api/v2/coupons/15.json

Option Sets cURL Commands

Here are sample cURL commands to handle option sets.

Connect Options to Option Sets

This is currently a four-step process.

  1. Create the option.
  2. Add some values to the option.
  3. Create the option set.
  4. Create option-set options, using the options you just created.

Use the following command to create an option:

    curl --request POST \
    -H "Content-Type: application/json" \
    -u "_username_:_API_key_" \
    -d '{"name":"homer simpson", "type":"T"}' \
    https://store.mybigcommerce.com/api/v2/options.json

BigCommerce returns the following, which includes an option ID:

{"id":33,"name":"homer simpson","display_name":"homer simpson","type":"T","values":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/options/33/values.json","resource":"/options/33/values"}}

Next, create a new option set:

    curl --request POST \
    -u "admin:key" \
    -d '{"name": "Simpson family"}' \
    -H "Content-Type: application/json" \
    https://store.mybigcommerce.com/api/v2/optionsets.json

The API returns the following, which includes an option-set ID:

{"id":27,"name":"Simpson family","options":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/optionsets/27/options.json","resource":"/optionsets/27/options"}}

The final step is to connect the option with the option set:

    curl --request POST \
    -u "_username_:_API_key_" \
    -d '{"option_id": "33", "display_name":"Simpson family"}' \
    -H "Content-Type: application/json" \
    https://store.mybigcommerce.com/api/v2/optionsets/27/options.json

Which yields the following:

{"id":44,"option_id":33,"option_set_id":27,"display_name":"Simpson family","sort_order":0,"is_required":false,"option":{"url":"https://store.mybigcommerce.com-bwvr466.mybigcommerce.com/api/v2/options/33.json","resource":"/options/33"}}


Testing Webhooks

Prerequisites

Create Project Folder

  1. Open the terminal and create a folder that will hold ngrok and the Node app, then move into that directory.
    mkdir webhooks-test
    cd webhooks-test

Install ngrok

There are three ways to install ngrok: - Install manually and then set the $PATH so ngrok can be used globally. - Download as an npm module. - Download manually and place in the project folder. (Method we are using)

Mac/Linux

  1. Visit https://ngrok.com/ and click on download.
  2. Choose the version for your operating system.
  3. Unzip ngrok and place the application in the project folder that you created.

This can be accomplished in one command: unzip “file_to_unzip” -d destination

unzip /Users/your-computer/Downloads/ngrok-stable-darwin-amd64.zip -d /Users/your-computer/Documents/webhooks-test

Windows

  1. Visit https://ngrok.com/ and click on download.
  2. Choose the version for your operating system.
  3. Unzip ngrok and place the application in the project folder that you created.
  4. Make sure the folder is in your PATH environment variable

Create Express App

  1. In the terminal run npm init. You will be prompted with several questions about the app setup. Feel free to hit return to accept the default value. The final screen will look something like this:
{
  "name": "webhooks-test",
  "version": "1.0.0",
  "description": "webhooks-test",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}
  1. Take note of the value in main, index.js.
  2. Create a file in your project folder called index.js. touch index.js
  3. Install Express using the terminal in the same project folder. npm install express --save
  1. Open index.js in a text editor and add this code snippet:
    const express = require('express')
    const app = express()
        app.post('/webhooks', function (req, res) {
        res.send('OK')
    })
    app.listen(3000, function () {
        console.log('Listening for webhooks on port 3000')
    })

The app is starting a server and listening on port 3000, then returning a response of ok once it receives a POST to the /webhooks url.

app.post('/webhooks', function (req, res) {
 res.send('OK')
})

From Express Website: app.METHOD(PATH, HANDLER) - app is an instance of express. - METHOD is an HTTP request method, in lowercase. - PATH is a path on the server. - HANDLER is the function executed when the route is matched. - Res.send is the body parameter that sends the HTTP response.

Start the app and ngrok

We are going to start the app and visit the ngrok url to see the status of our webhooks.

  1. Open two terminal tabs. They both should be in your project folder.
  2. In one tab run the app. node index.js
  3. In the other start ngrok. ./ngrok http 3000

index.js tab will have: Listening for webhooks on port 3000

./ngrok http 3000 tab will have something like this:

ngrok terminal example

ngrok returns two values we need for webhooks. - Web Interface: Where you can monitor the hook from a browser. https://127.0.0.1:4040 - Forwarding: The webhook destination. Make note of the https version. In this example its https://6a35e97b.ngrok.io.

  1. Open a web browser and copy in your Web Interface URL. http://127.0.0.1:4040 - This is where the webhooks will appear when they fire.

ngrok no responses

Create the webhook

The webhook we are going to subscribe to is store/product/updated.

  1. In Postman create a POST request using https://api.bigcommerce.com/stores/{{store_hash}}/v2/hooks. Replace store_hash with your store.
  2. Create a body request with the webhook we are subscribing to and your forwarding url:
{
 "scope": "store/product/updated",
 "destination": "https://6a35e97b.ngrok.io/webhooks",
 "is_active": true
}

The destination url is the forwarding url from ngrok and /webhooks, matching the URL path set in the app POST.

  1. Update the headers to have: Accept: application/json Content-Type: application/json X-Auth-Client: {{the OAuth client id}} X-Auth-Token: {{the OAuth token}}
  2. Check all the values and then hit POST. The response will be 201 Created if headers and scope are correct.

postman create hook

Fire Webhooks

You can fire the webhook in two ways. Either the API or the store’s control panel. We are going to cover both.

Update via the Control Panel

  1. From your store’s control panel, navigate to Products > View. Choose a product and change some of the information. In this case, the word Hoodie was added to the product name. Then click save.

BigCommerce Control Panel

2.Visit the Ngrok web interface address (in the sample app it’s http://127.0.0.1:4040), and check for a 200 response.

ngrok web app product updated

Under Summary, you can see the webhook has fired. It returned the text OK. This can be changed. In the original app, res.send(‘OK’). This can be changed to say something different or even post the response to another app. The response will also show in the terminal.

terminal response

Update via the API

Create a PUT request to the product that needs to be updated.

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/124

In this example, the price of produc_id 124 is being changed to 12.99.

After hitting send, check the ngrok web interface. You may have more or less events based on how many times the product has been updated.

Product Updated Ngrok

That’s it. In this walkthrough, you created a webhook, set up a server to accept the response and used Express.

Next Steps

Additionally, you can change the text in res.send() to have a custom response, print the response to a webpage or set up a different webhook. You can also send in custom headers as a way to verify the hook or get custom hook information back. Setup the destination using a permanent url such as creating an Heroku app, then having the response print to the screen.

To send in custom headers, during the /POST or /PUT request add in:

{
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "{secret_auth_password}"
  },
  "destination": "https://app.example.com/orders",
  "is_active": true
}

The custom header can be anything you choose. It can be used to check the security of an incoming webhook. Anything without the custom header should be rejected.

Response:

{
    "id": 14422996,
    "client_id": "{{client_id}}",
    "store_hash": "{{store-hash}}",
    "scope": "store/product/updated",
    "destination": "https://6a35e97b.ngrok.io/webhooks",
    "headers": {
        "A-Custom-Header": "some-secret-password"
    },
    "is_active": true,
    "created_at": 1533142869,
    "updated_at": 1533142869
}

Troubleshooting

  1. Getting a 404 error using the root (/) url?

Add this snippet to your code to respond to incoming get requests with ‘hello’.

app.get('/',(req, res)=>{
    res.send('Hello!');
}); 

2.Getting error ngrok not found? There are two ways to fix this. Your local setup will determine which command will work. Use the command mv ngrok /usr/local/binto move ngrok to your local bin folder. This way it becomes available globally. Use the command ./ngrok http 3000 to run ngrok as a sudo user.