> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # 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. | Code | Text | Purpose | | :-----: | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **200** | **OK** | For successful `GET` and `PUT` requests. | | **201** | **Created** | For a successful `POST` request. | | **202** | **Accepted** | For a request that resulted in a scheduled task being created to perform the actual request. | | **204** | **No Content** | For a successful request that produced no response (such as `DELETE` requests). | | **207** | **Multi-Status** | Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred. | ### 3xx Redirection 3xx codes are returned for requests that require further action. | Code | Text | Purpose | | :-----: | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **301** | **Moved Permanently** | When the API routes have changed (unlikely), or if the incoming request is not secure (`http`), the request will be redirected to the secure (`https`) version. | | **304** | **Not Modified** | This response will be sent if the request included an `If-Modified-Since` header, but the resource has *not* been modified since the specified date. | ### 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](/developer/docs/overview/api-fundamentals/integration-design#404-and-422-client-errors). | Code | Text | Purpose | | :-----: | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **400** | **Bad Request** | Issued when a malformed request was sent. The request could not be completed due to a URL restriction. Check the URL for ports that may conflict with site permissions. | | **401** | **Unauthorized** | This response is sent when your client failed to provide credentials or its credentials were invalid. | | **403** | **Forbidden** | Returned when permissions do not allow the operation. | | **404** | **Does Not Exist** | The requested entity does not exist. | | **405** | **Method Not Allowed** | The resource was found, but doesn't support the request method. Issued when either a specific method isn't yet implemented on a resource, or the resource doesn't support the method at all. For example, a `PUT` on `/orders` is invalid, but a `PUT` on `/orders/{_id_}` is valid. | | **406** | **Not Acceptable** | When the client specifies a response content type in the `Accept` header that is not supported. | | **409** | **Conflict** | A change requested by the client is being rejected, due to a condition imposed by the server. The exact reasons for this response will vary from one resource to the next. An example might be attempting to delete a category whose deletion would cause products to be orphaned. Additional information about the conflict, and about how to resolve it, might be available in the response's `details` section. | | **413** | **Request Entity Too Large** | When the client requests too many objects. For example, the `limit` parameter exceeded the maximum. | | **415** | **Unsupported Media Type** | Returned due to issues with the `Content-Type` header. | | **422** | **Missing or Invalid Data** | The request cannot be processed either because it omitted required fields or because it contained invalid data. See the response for more details. | | **423** | **Locked Status Code** | The requested resource is currently locked and unavailable. | | **429** | **Too Many Requests** | When an OAuth client exceeds the [rate limit](/developer/docs/overview/api-fundamentals/rate-limits) for API requests to a store. | | **499** | **Client Closed Request** | A client terminates the connection before receiving a response. | ### 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](/developer/docs/overview/api-fundamentals/integration-design#500-through-504-server-errors). | Code | Text | Purpose | | :-----: | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **500** | **Internal Server Error** | When an error has occurred within the API. | | **501** | **Not Implemented** | When a request method is sent that is not supported by the API (e.g., `TRACE`, `PATCH`). | | **503** | **Service Unavailable** | When the store is "Down for Maintenance," being upgraded to a new version, or is suspended due to administrative action or a billing issue. | | **507** | **Insufficient Storage** | When the store has reached a limitation for the resource, according to their [BigCommerce plan](https://support.bigcommerce.com/s/article/Pricing#plan-features) (e.g., 500-product limit). | ### Troubleshooting | Code | Common Causes | Solutions | | :---------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **204**, **301**, and **302** | Redirects | Try the `www` or non-`www` version of the URL. | | **400** | Invalid syntax, required data missing, `content-type` header missing | Double-check request body for syntax errors and missing data; check `content-type` header. | | **401** | API credentials are missing or invalid. | Double-check the `access_token` and `client_id`. | | | | Send cURL request with the same credentials to rule app or config issues. | | **403** | App lacks required OAuth scopes, a store-owner account changed, operations resulting from API request exceed a platform limit, or URL requested is incorrect. User does not have app install or uninstall permissions. | Double-check OAuth Scopes in **control panel** > **API Accounts** or in **Developer Portal** > **My Apps**. | | | | Check the URL. Are the endpoint and store hash correct? | | | | Ensure [platform limits](https://support.bigcommerce.com/s/article/Platform-Limits#product-catalog-limits) have not been reached. | | **415** | Request headers specify an unsupported `content-type` (or header is missing). | Double-check `content-type` request header. | | **500** | Expensive API calls or an internal server error in BigCommerce. | Re-attempt the request three to five times, with increasing delays of at least a minute between attempts. | | | | Try reducing the number of objects being requested. You can request fewer objects in the v2 API, by using `?limit={count}`. In `v2` and `v3` API, fewer objects can be requested by excluding certain fields or only requesting certain fields. | | | | Check the BigCommerce [Status Page](https://status.bigcommerce.com/). | ## 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: | Operator | Expression | Example | | ----------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- | | Equals/equivalency | attribute=value | `/v3/catalog/products?price=10` `/v3/catalog/products?name=My Product` | | Greater than or equal to (for numbers or dates) | attribute:min=value | `/v3/catalog/products?price:min=10` | | Less than or equal to (for numbers or dates) | attribute:max=value | `/v3/catalog/products?price:max=10` | | Greater than (for numbers or dates) | attribute:greater=value | `/v3/catalog/products?price:greater=10` | | Less than (for numbers or dates) | attribute:less=value | `/v3/catalog/products?price:less=10` | | SQL LIKE operator (for strings) | attribute:like=pattern | `/v3/catalog/categories?name:like=Shirts` | | SQL IN operator (for arrays) | attribute:in=csv,list of values | `/v3/catalog/products?categories:in=123,456` | | SQL NOT IN operator (for arrays) | attribute:not\_in=csv,list of values | `/v3/catalog/products?categories:not_in=123,456` | 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: **`Example response: Product name and price`** ```http title="Example response: Product name and price" showLineNumbers={false} 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 | Header | Expected value or type | Description | Example | | :-------------- | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | | `Accept` | MIME types | The MIME type format that indicates which response type the request expects. For more information, see [HTTP Docs: Accept Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept). | `application/json` | | `Content-Type` | MIME types | The MIME type of the request body. The API uses this value to validate and parse the request. For more information, see [HTTP Docs: Content-Type Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type). | `application/json` | | `User-Agent` | String | We ask that you specify a user agent to identify your integration or client. | `PostmanRuntime/7.32.3` | | `Authorization` | String | Requests to the [Process payments](/developer/api-reference/rest/admin/payments) endpoint and the [GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api) use the `Authorization` header to authenticate. For more information, see [HTTP Docs: Authorization Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). | `Bearer {{STOREFRONT_TOKEN}}` or `PAT {{PAYMENT_ACCESS_TOKEN}}` | ### BigCommerce-specific request headers | Header | Expected value or type | Description | | :----------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `X-Auth-Token` | API account access token | Requests to the REST Management, Catalog, GraphQL Admin, and GraphQL Account APIs use this header to authenticate. Some Payment endpoints also use this header. | | `X-Auth-Client` | API account client ID | No longer required for any requests to BigCommerce. | | `X-Correlation-Id` | UUID in an 8-4-4-4-12 format | An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce for WordPress. For more information, see [Best Practices](/developer/docs/storefront/headless/overview#correlating-requests) or the [Headless Guide](/developer/docs/storefront/headless#correlating-requests). | ### 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: **`Example request body: Product object`** ```json title="Example request body: Product object" showLineNumbers={false} { "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](https://www.rfc-editor.org/rfc/rfc9110.html#name-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 | Header | Possible Values | Description | Example | | :------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------ | :------------------------------ | | `Date` | An [RFC 2822](http://tools.ietf.org/html/rfc2822#section-3.3) date. | The date the response was sent. | `Tue, 15 Nov 2011 12:45:26 GMT` | | `last-modified` | An [RFC 2822](http://tools.ietf.org/html/rfc2822#section-3.3) 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` | | `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` | ### BigCommerce-specific response headers | Header | Possible Values | Description | Example | | :---------------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | `X-Rate-Limit-Time-Window-Ms` | number | Shows the size of your current rate-limiting window, in milliseconds. | `30000` | | `X-Rate-Limit-Time-Reset-Ms` | number | Shows how many milliseconds are remaining in the window. In this case, 15000 milliseconds – so, 15000 milliseconds after this request, the API quota will be refreshed. | `15000 ` | | `X-Rate-Limit-Requests-Quota` | number | Shows how many API requests are allowed in the current window for your client. | `150` | | `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 35 more requests in the next 15000 milliseconds; on the 36th request within 15000 milliseconds, you would be rate-limited and receive an HTTP 429 response. | `35` | | `X-Retry-After` | integer | Rate limited response, indicating the number of seconds before the quota refreshes. See [Rate Limits](/developer/docs/overview/api-fundamentals/rate-limits) for more information. | `15` | | `X-BC-ApiLimit-Remaining` | integer | The number of API requests remaining for the current period (rolling one hour). | `987` | | `X-BC-Store-Version` | A version number | The version of BigCommerce on which the store is running. This header is available on versions 7.3.6+. | ` 7.3.6` | ### 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. **`Example request: Get a category`** ```http title="Example request: Get a category" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories/{{category_id}} ``` **`Example response: Get a category`** ```json title="Example response: Get a category" showLineNumbers={false} { "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": {} } ```