API Environment

BigCommerce API requests can be made in the context of the storefront or server-to-server.

  • Storefront APIs use the store url: https://your-store.mybigcommerce.com/api/{endpoint}
  • Server-to-Server requests use the base url: https://api.bigcommerce.com/stores/{store_hash}/v3/
  • V2 API Requests use the base url: https://api.bigcommerce.com/stores/{store_hash}/v2/

Request Headers

Server-to-Server request headers require Accept, X-Auth-Client, X-Auth-Token and Content-Type at a minimum.

Header Allowed Values Description Example
Accept application/json (for .json requests) application/xml (for .xml requests) The MIME type for the format you want to receive a response in. application/xml
Content-Type application/json (for JSON requests) application/xml (for XML requests) The MIME type of the request body. Used to validate and parse the request to the API. application/json
User-Agent String While it is not required, we ask that you specify a user agent which identifies your integration/client with your requests.
X-Auth-Client String Client ID of the requesting app
X-Auth-Token String Access token authorizing the app to access resources on behalf of a user

Response Headers

Header Possible Values Description Example
Date An RFC 2822 date. The date the response was sent. Tue, 15 Nov 2011 12:45:26 GMT
last-modified An RFC 2822 date. The date the resource was last modified. Please refer to the individual resource pages for support for this header. Tue, 15 Nov 2011 12:45:26 GMT
Content-Type application/json The MIME type of the response, dependent on the extension of the endpoint that was requested. application/json
Content-Location A URI Sent if the request was redirected. /api/v2/orders/5.json
Location A URI The URI of a newly created resource. Sent with a 201 Created response. /api/v2/products/7
X-Retry-After integer Rate limited response, indicating the number of seconds before the quota refreshes. See Rate Limits for more information. 15
X-BC-ApiLimit-Remaining integer The number of API requests remaining for the current period (rolling one hour). See Rate Limits for more information. 987
X-BC-Store-Version A version number The version of BigCommerce the store is running on. This header is available on versions 7.3.6+. 7.3.6
Content-Encoding gzip Allows API clients to request content to be compressed before being sent back in the response to an API request. gzip
Transfer-Encoding chunked Specifies the form of encoding used to transfer the resource. chunked
X-Rate-Limit-Requests-Left number Details how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 6 more requests in the next 3000 milliseconds; on the 7th request within 3000 milliseconds, you would be rate-limited and would receive an HTTP 429 response. 16101491
X-Rate-Limit-Requests-Quota number Shows how many API requests are allowed in the current window for your client. 16101495
X-Rate-Limit-Time-Reset-Ms number Shows how many milliseconds are remaining in the window. In this case, 3000 milliseconds – so, 3000 milliseconds after this request, the API quota will be refreshed. 30000
X-Rate-Limit-Time-Window-Ms number Shows the size of your current rate-limiting window. 9762

Media Types

A media type is the format of the request or response body. The BigCommerce API accepts requests and responds in JSON. You should encode requests using the UTF-8 character set. (Other character sets might have unpredictable results).

Content Types

Request Content Type

When performing a request that contains a body (eg. POST or PUT), the type of content you are sending needs to be specified in the Content-Type header.

Response Content Type

There are two ways you can specify the type of content you would like to receive. The first method is to specify an Accept header. The second is to supply an extension to the resource you are requesting.

The priority in which these methods are processed are:

  • Accept header high-priority types (eg. Accept: application/json) extensions on the resource (e.g. customers.json).
  • Accept header low priority types (priorities less than 1, e.g. Accept: application/json;q=0.9)

Request and Response Structure

Request Structure

The body of a JSON request is an object containing a set of key-value pairs. A simple representation of a product object is:

{
     "id": 5,
     "name": "iPod",
     "description": "A portable MP3 music player."
 } 

Response Structure

Responses are structured similarly to requests. If a request returns a single object, then the response will contain a single object, containing the fields for that resource.

Single Category
{
  "data": {
    "id": 39,
    "parent_id": 19,
    "name": "Bath",
    "description": "",
    "views": 0,
    "sort_order": 0,
    "page_title": "",
    "meta_keywords": [
      ""
    ],
    "meta_description": "",
    "layout_file": "category.html",
    "image_url": "",
    "is_visible": true,
    "search_keywords": "",
    "default_product_sort": "use_store_settings",
    "custom_url": {
      "url": "/garden/bath/",
      "is_customized": false
    }
  },
  "meta": {}
}

If the request returns more than one result, then the response will consist of an array of objects for each result:

Multiple Categories
{
  "data": [
    {
      "id": 19,
      "parent_id": 0,
      "name": "Garden",
      "description": "<p>A collection of products for the garden.</p>",
      "views": 0,
      "sort_order": 2,
      "page_title": "page title",
      "meta_keywords": [
        "meta keyword"
      ],
      "meta_description": "meta description",
      "layout_file": "category.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "search keywords",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/garden/",
        "is_customized": false
      }
    },
    {
      "id": 20,
      "parent_id": 0,
      "name": "Publications",
      "description": "",
      "views": 0,
      "sort_order": 4,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/publications/",
        "is_customized": false
      }
    },
    {
      "id": 21,
      "parent_id": 0,
      "name": "Kitchen",
      "description": "",
      "views": 0,
      "sort_order": 3,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/kitchen/",
        "is_customized": false
      }
    },
    {
      "id": 22,
      "parent_id": 0,
      "name": "Utility",
      "description": "",
      "views": 0,
      "sort_order": 5,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/utility/",
        "is_customized": false
      }
    },
    {
      "id": 23,
      "parent_id": 0,
      "name": "Shop All",
      "description": "<h1>Browse our full collection</h1>",
      "views": 0,
      "sort_order": 0,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category_with_facets.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/shop-all/",
        "is_customized": false
      }
    },
    {
      "id": 39,
      "parent_id": 19,
      "name": "Bath",
      "description": "",
      "views": 0,
      "sort_order": 0,
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "layout_file": "category.html",
      "image_url": "",
      "is_visible": true,
      "search_keywords": "",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "/garden/bath/",
        "is_customized": false
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 6,
      "count": 6,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}