API Best Practices
BigCommerce frequently enhances its core product and is actively enhancing REST endpoints, as well as expanding the graphs accessible to our growing family of 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.
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
- 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
- Adding new optional fields to
- 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.
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.
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.
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.
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 & sandboxes
|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)
|60k per hour (450 / 30sec)
|Plus & Standard plans
|20k 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.
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:
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 encoutering rate limits, see About Our API.
When you see a response with an HTTP
429 status code, your client shouldn’t make any further requests until your quota has refreshed:
HTTP/1.1 429 Too Many Requests
Date: Mon, 03 Feb 2022 20:36:00 GMT
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:
$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.
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
- Determining an acceptable average rate of requests by dividing
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.
- Platform Limits (Help Center) (opens in a new tab)
- API Terms of Service (bigcommerce.com) (opens in a new tab)
- Filtering Requests
- API Status Codes
- About Our API: Response Headers
- Guide to API Accountswebhook events and their payloads
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.
- API Reference
- REST Storefront Cart API
- Upsert price list records
- BigCommerce Ruby API client (GitHub) (opens in a new tab)