Docs
Getting started
Development
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.

Looking for more information on handling requests? Continue with API rate limits to learn about our best practices.

Resources

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.

Resources

Related articles

API references and clients

External articles

Did you find what you were looking for?
Passwordless loginAPI rate limits