REST API Overview

This page covers REST API HTTP status codes and common query parameters for BigCommerce REST APIs.

REST HTTP status codes

BigCommerce REST APIs respond to each request with an HTTP status code that depends on the result from the request. Error responses might also include an error message in the body to assist in resolving the problem.

2xx Success

2xx codes are returned for requests that were understood and processed successfully.

3xx Redirection

3xx codes are returned for requests that require further action.

4xx Client Error

4xx codes are returned for requests that could not be processed due to problems with the request or the data. For more information on handling 400 errors skillfully, see API Request Architecture.

5xx Server Error

5xx codes are returned for requests that could not be processed due to an internal error with the API or server. For more information on handling 500 errors skillfully, see API Request Architecture.

Troubleshooting

Filtering

To filter collections down to a particular set of items, you can add filters to your request as URL query parameters.

The maximum number of products returned is 250. Viewing more products requires creating a script that can loop through each subsequent page.

These are the most common filter options available for the REST Management API:

Available filters vary by endpoint. For up-to-date information on supported filters, refer to the GET method documentation of each endpoint.

Include

Certain endpoints support the include query parameter used to include sub-resources and specific attributes in the primary GET response for a parent object. For example, you can include a product’s variants and images with the product response:

/v3/catalog/products?include=variants,images

The availability of the include query parameter varies by endpoint. For up-to-date filter information, refer to the GET method documentation of each endpoint.

For more information about whether an endpoint supports the include parameter, consult the API reference for the endpoint in question.

Include and exclude fields

Many of BigCommerce’s REST API endpoints support both include_fields and exclude_fields query parameters.

• include_fields query parameter will return ONLY the specified fields in the response.
• exclude_fields query parameter will omit the specified fields from the response.

You can request any field that is available on the object. Speed up your API request response time by excluding unnecessary fields from your request, especially large fields like descriptions.

The following example shows product name and price included in a single request:

GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products?include_fields=name,price
{
    "data": [
        {
            "id": 77,
            "name": "Red printed scarf",
            "price": 12
        }
    ]
}

The availability of the include_fields and exclude_fields query parameters varies by endpoint. For up-to-date filter information, refer to the GET method documentation of each endpoint.

Pagination and limit

• page is the number of pages that are returned by the API.
• limit is the number of results per page that are returned.
• page=2&limit=10 will return page 2 of the results with 10 items per page.
• The maximum number of products returned is 250.

Media types

A media type is the format of the request or response body. BigCommerce APIs accept requests and send responses in JSON. Encode requests using the UTF-8 character set; other character sets can have unpredictable results.

Requests

For more information about required request headers, consult the API reference for the endpoint or graph you want to use.

Standard request headers

BigCommerce-specific request headers

Request content type

When performing a request that contains a body, specify the type of content you are sending with the Content-Type header. This typically applies to PUT and POST requests.

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

Responses

Response headers

HTTP response header names are case-insensitive; see the HTTP specification on field names for more information. For example, your application may receive x-rate-limit-requests-left rather than X-Rate-Limit-Requests-Left, so plan your implementation accordingly. Most open source HTTP clients treat headers with the appropriate case insensitivity.

Standard response headers

BigCommerce-specific response headers

Response content type

When requesting a resource that returns a body, specify the type of content you want to receive with the Accept header. Alternatively, you can supply an extension to the resource you’re requesting.

The priorities with which you can process these methods are:

• Accept header high-priority types (e.g. 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)

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.

GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories/{{category_id}}

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