REST API Quick Start

This Quick Start guide will take you through the minimum required steps to begin making API requests against BigCommerce’s V2 and V3 REST APIs.

By the end of this guide, you’ll be able to:

  • get a list of products
  • create a product
  • troubleshoot common errors

Prerequisites

Authentication

For simplicity, we’ll be using Store API Credentials in this tutorial. To obtain Store API credentials, do one of the following:

  1. Generate Store API Credentials in your store’s control panel (if you’re a store owner).
  2. Request your store owner to generate API credentials on your behalf.
  3. Generate Store API Credentials by signing up for a free trial.

For more information on authentication and types of API credentials, see:

Making Requests

The easiest way to experiment with BigCommerce REST APIs is via the built-in Request Runner:

Open in Request Runner

Just copy and paste your store_hash, client_id ID, and access_token into the form, then click Send

If you use Visual Studio Code, another simple way to make API requests is with the REST Client extension. Once you have it installed, create a new file called bigcommerce.http and paste in the following:

@ACCESS_TOKEN = your_access_token
@CLIENT_ID = your_client_id
@STORE_HASH = your_store_hash

###

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

Save and you’ll see the send request link above GET. Click send request and the response will open in a split window.

Alternatively, you can import the Specification File into Postman (or any other tool that can import Open API Specification files).

Get all Products

To get a paginated list of all products, make a GET request to /catalog/products:

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

Open in Request Runner

Example Response:

{
  "data": [
    {
      "id": 174,
      "name": "1L Le Parfait Jar",
      "type": "physical",
      "sku": "",
      "description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
      ...
    },
    ...
    "meta": {
      "pagination": {
        "total": 120,
        "count": 30,
        "per_page": 30,
        "current_page": 1,
        "total_pages": 4,
        "links": {
          "next": "?page=2",
          "current": "?page=1"
        },
        "too_many": false
      }
  }

Note:: replace {store_hash} with the store hash shown when generating the API credentials):

Get Ten Products Sorted by Name

Results can be filtered and sorted by appending query string parameters to the end of the URL:

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products?limit=10&sort=name
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

Open in Request Runner

Example Response:

{
  "data": [
    {
      "id": 174,
      "name": "1L Le Parfait Jar",
      "type": "physical",
      "sku": "",
      "description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
      ...
    },
    ...
    "meta": {
      "pagination": {
        "total": 120,
        "count": 10,
        "per_page": 10,
        "current_page": 1,
        ...
      }
  }

For a list of product filters, see API Reference > Products > Get All Products > Request Parameters > Query Parameters.

Create a Product

Before we can create a product, we’ll first need to get the id of a category to add the product to (categories is a required field for creating products). We can do this with a GET request to /catalog/categories:

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

Open in Request Runner

Example Response:

{
  "data": [
    {
      "custom_url": {
        "is_customized": false,
        "url": "/t-shirts/"
      },
      "default_product_sort": "use_store_settings",
      "description": "The Best T-Shirts",
      "id": 2,
      ...
    },
    ...
  ],
  ...
}

Once we have a category id, we can create a product with the minimum required fields (notice the id from the previous request in the categories array):

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

{
  "name": "BigCommerce Hoodie",
  "type": "physical",
  "weight": 5,
  "width": 12,
  "price": 25.99,
  "categories": [
    2
  ],
}

Open in Request Runner

Property Type Description
name string The name of of the product
price number the price of the product
categories array list of categories the product belongs to
type enum physical or digital
weight number how much the product weighs; used for shipping calculations

Next Steps

Troubleshooting

Did you get a status of 403 Forbidden?

  • Make sure Client ID and Access Token are correct and have scope set to Products Modify.
  • Make sure your request headers are correct.
  • Be sure you replaced {store_hash} with your store hash.
  • Make sure the request URL is correct.

Did you get a 200 but nothing was returned?

  • Make sure your store has products.

Did you get a status of 404?

  • Check the request URL for errors.