Getting started
API requests

API Best Practices

Keep your integration up to date

BigCommerce frequently enhances its core product and is actively enhancing REST endpoints, as well as expanding the graphs accessible to our GraphQL APIs. Using the latest information lets you update your app to take advantage of the most current resources. You also position your app or implementation to provide a user experience consistent with what merchants see in their BigCommerce store control panel. To stay up to date, bookmark our changelog.

Anticipate changes to BigCommerce APIs

At BigCommerce, we make a distinction between "breaking" and "non-breaking" changes.

In most cases, we will give advance notice in our developer changelog when we make any of the following "breaking" changes. However, we will make breaking changes without warning to alpha and beta endpoints and graph nodes, or when analytics indicate that an endpoint has no traffic for three months.

Examples of breaking changes include:

  • Removing fields from API responses
  • Changing the data type of request or response fields
  • Changing the structure of request or response objects
  • Adding new required fields to POST and PUT request bodies
  • Removing endpoints

We will push "non-breaking" changes to the code base without warning as part of our normal development.

Examples of non-breaking changes include:

  • Adding new fields to GET request responses
  • Adding new optional fields to POST and PUT request bodies
  • Adding new endpoints

We encourage you to write robust, resilient code that will not break or leak memory if an endpoint begins to return additional fields.

Use webhooks to listen for changes

To keep your app's data up to date, webhooks provide a great alternative to periodic API polling. Use a store-level or app-level API account to register and subscribe to webhook-enabled events relevant to your app.

When an event your app is listening for occurs, BigCommerce sends a payload with a few identifying details relevant to the event. See a list of webhook events and their payloads. Use the payload data points to make subsequent API requests for more details.

Avoid polling the Storefront Cart API

Client-side applications should avoid polling the REST Storefront Cart API on interval. Millions of browsers could poll this API at any given time, causing a significant load increase to BigCommerce's servers. We may take action against a store using this practice to prevent service interruptions to other stores.

As an alternative, consider using a server-side app to subscribe to cart webhook events, then query the Storefront Cart API only as a response to user input. Storing cart information in the browser cache is an alternative method for updating cart information across browser tabs. You may also be interested in the growing list of events available to native storefronts with our Open Data Layer enabled.

Thread API requests

You can use threaded requests in order to quickly update information in an API. Threaded requests allow you to send multiple requests at one time. They can come from a different open connection or multiple requests to the same resource.

The BigCommerce Ruby API client (opens in a new tab) is thread-safe. It satisfies both the need for multiple threads to access the same shared data and the need for only one thread to access a shared piece of data at any given time. This design pattern can reduce the total time that your app requires to complete a series of requests.

API rate limits

Apps that authenticate with OAuth are rate-limited based on a quota that is refreshed every few seconds. The maximum quota for a store will vary depending on the store plan and resources requested.

Plans & sandboxesQuotas
Enterprise plans and Enterprise sandboxes (Enterprise-Test)by plan* and resource (opens in a new tab)
All other sandboxes (Dev/Partner/Employee)by resource (opens in a new tab)
Pro plans60k per hour (450 / 30sec)
Plus & Standard plans20k per hour (150 / 30sec)

* The Unlimited rate plan for select BigCommerce Enterprise clients means that these stores are not rate limited by number of requests per unit of time. However, there are physical infrastructure-related constraints that may limit the maximum throughput of requests for a given resource. For more on resource constraints, consult our article on object-related limits (Help Center) (opens in a new tab).

BigCommerce reserves the right to limit unreasonable or abusive API activity in the interest of platform stability, per our Terms of Service (opens in a new tab).

Each request to the API consumes one available request from the quota. When an app hits the quota limit, subsequent requests are rejected until the quota is refreshed.

A store’s overall quota is distributed across all apps that are accessing that store at a given time. This prevents a single app from consuming the store’s entire quota by itself. The quota available to a single app adjusts as additional clients start and stop making requests.

Playing nicely with the platform

As of January 2022, BigCommerce header field names became functionally case-insensitive. Learn more about BigCommerce response header conventions.

Every API response’s HTTP headers give you full visibility into your position in the rate-limiting algorithm:

Standard plan example: Rate limit headers
X-Rate-Limit-Time-Window-Ms: 30000
X-Rate-Limit-Time-Reset-Ms: 15000
X-Rate-Limit-Requests-Quota: 150
X-Rate-Limit-Requests-Left: 35

If your implementation's request to the API triggers a 429: Too Many Requests response, it is encountering rate limits. Responses contain the X-Rate-Limit-Time-Reset-Ms header, which specifies the time in milliseconds that your client must wait before its quota refreshes. Retry the request after this time has elapsed.

For more about rate limit headers and how to calculate the timing of your requests to reduce the risk of encountering rate limits, see About Our API.

Example of 429 status code

When you see a response with an HTTP 429 status code, your client shouldn’t make any further requests until your quota has refreshed:

Example: 429 response
  HTTP/1.1 429 Too Many Requests
  Date: Mon, 03 Feb 2022 20:36:00 GMT
  Content-Type: application/json
  X-Rate-Limit-Time-Reset-Ms: 15000

Parse the X-Rate-Limit-Time-Reset-Ms header to determine how long you have to wait. In this case, it would be 15000 milliseconds. Your client can sleep on the specified interval:

PHP example for delaying response
  $milliseconds = $response->getHeader("X-Rate-Limit-Time-Reset-Ms");

After waiting for the given number of milliseconds, your client can go back to making API requests.

Making requests in parallel

You can increase the amount of work your app can do in a given unit of time by sending multiple HTTP requests in parallel. This is perfectly acceptable. However, your app should monitor the rate limiting headers to avoid an HTTP 429 response. Methods for doing this include the following:

  • Slowing your rate of API requests as X-Rate-Limit-Requests-Left approaches zero.
  • Determining an acceptable average rate of requests by dividing X-Rate-Limit-Requests-Quota by X-Rate-Limit-Time-Window-Ms, and then self-throttling to that rate.

Endpoints that accept bulk requests may have specific limitations on the number of accepted parallel requests. For example, making multiple parallel requests to Upsert price list records results in one or more error responses with the 429: Too Many Requests status code. The current list of limitations is documented in our article on resource-specific limits (Help Center) (opens in a new tab). The API reference specification for each endpoint or mutation also documents any limits specific to that request.


API platform

Correlating requests

When building a headless storefront, it's best practice to group related requests using the X-Correlation-Id header. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our list of request headers. For an example and a more in-depth explanation, see the Introduction to Headless Commerce.


Related articles

API references and clients

External articles

Did you find what you were looking for?