NAV
Subscribe to developer updates

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.

Postman/OAuth Quickstart Guide

This section shows you how to quickly get started exercising BigCommerce APIs, using the Postman app.

To get started, you’ll need OAuth credentials to supply to Postman. BigCommerce uses OAuth 2.0.

Creating OAuth2.0 Credentials

Create your OAuth 2.0 credentials as described under Obtaining OAuth Tokens. (Depending on what scopes you set, you will be limited in what objects you can request. You can view scope information here.)

Postman Setup

You’ll do the next steps in the Postman app.

Select No Auth

In Postman, set the Type drop-down list to No Auth (so as to create only the OAuth headers that you need). This will display the form shown below:

Populate Auth Headers

Select the Headers tab to display the form shown below:

Next, add these two key/value pairs, using the OAuth credentials you obtained in the BigCommerce control panel:

Key Value
X-Auth-Client The Client ID you obtained when you created your OAuth token.
X-Auth-Token The Access Token string you obtained when you created your OAuth token.

Sending a Request

We have created a collection of Postman requests for our v3 API, which you can import by clicking the button below:

Run in Postman

To use this collection, you’ll need to enter your OAuth credentials, as explained above under Postman Setup.

You’ll also need to enter your store’s API Path, as displayed in the control panel. You can do so in either of these ways:

Now you can send and receive information through an OAuth API connection with BigCommerce. If you’d like to register webhooks through Postman, please see Creating Webhooks: Sending the POST Request.

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"}}