App Development Best Practices

Review the following best practices before submitting your app to the Apps Marketplace.

OAuth flow

Follow security best practices and requirements

RFC 6749 discusses OAuth security considerations, recommendations, and requirements. Here’s a summary of important items applicable to apps:

  • Request access tokens with minimal scopes necessary.
  • Serve all redirect URIs over TLS.
  • Keep access tokens confidential in transit and storage.
  • Do not transmit access tokens, refresh tokens, or client credentials in the clear.
  • Do not transmit authorization codes in the clear.
  • Educate end-users about the risks phishing attacks pose.
  • Provide mechanisms that make it easy for end-users to confirm the authenticity of your app.
  • Implement CSRF protection on redirect URI.

For details, see Security Considerations in RC6749. For a list of the top web application security risks and best practices to avoid them, see OWASP Top Ten.

API requests

Use the latest APIs

BigCommerce is actively developing V3 API endpoints. By using the newest endpoints, you will ensure that your app has access to the latest resources. You will also be better positioned to provide a user experience consistent with what merchants will see in their BigCommerce store’s control panel. To stay up to date, bookmark our changelog.

Plan for API updates

We encourage developers to write code against our API that will not break if an endpoint starts returning additional fields, as these “non-breaking” changes may be made by us without warning as part of our normal development. Breaking changes will be made with early warning, typically via our developer changelog and other channels as appropriate. For beta APIs and in exceptional cases where we know using a particular endpoint to be zero, we may make breaking changes without warning.

Thread API requests

Thread requests to make rapid updates via API. Threaded requests allow you to send multiple requests at a time. They can come from a different open connection or multiple requests to the same resource. Our Ruby API client is thread-safe; it satisfies the need for multiple threads to access the same shared data and the need for a shared piece of data to be accessed by only one thread at a time. These attributes can reduce the total time that your app will require to complete a series of requests.

Respect API rate limits

BigCommerce rate limits all API requests made to a store in a thirty-second window. The rate limit varies by plan level.

Plan Requests per Hour Requests per 30 Seconds
Enterprise - 7,000,000
Enterprise Sandboxes - 7,000,000
Pro 60,000 450
Plus 20,000 150
Standard 20,000 150
Non-Enterprise Sandboxes 20,000 150

Apps making API requests to a store share the store’s rate limit. This promotes fairness between apps accessing the API simultaneously, and prevents a single app from consuming the store’s entire limit.

BigCommerce allots applications a share of a store’s rate limit via quota system, and exposes rate limit positioning to applications via the following response headers.

X-Rate-Limit-Requests-Left →6
X-Rate-Limit-Requests-Quota →25
X-Rate-Limit-Time-Reset-Ms →3000
X-Rate-Limit-Time-Window-Ms →5000
Name Description
X-Rate-Limit-Time-Window-Ms size of rate limit window in milliseconds
X-Rate-Limit-Time-Reset-Ms time remaining in window in milliseconds
X-Rate-Limit-Requests-Quota total requests allotted to your application per window
X-Rate-Limit-Requests-Left remaining requests allotted to your application in current window

BigCommerce responds to apps that exceed the quota with a 429 response. When this happens, applications should pause requests until the number of milliseconds in X-Rate-Limit-Time-Reset-Ms elapses.

Understand concurrent API request limits

BigCommerce limits concurrent requests to most endpoints to three. The endpoints specified below enjoy an increased limit.

Limit Endpoint Method
10 /v3/customers POST

Play nicely when making parallel requests

BigCommerce’s REST endpoints accept requests made in parallel. Applications making parallel requests should monitor rate limit headers to avoid a 429 response. Methods for doing so include the following:

  • Slow rate of requests when X-Rate-Limit-Requests-Left nears zero.
  • Self-throttles requests to the average rate of (X-Rate-Limit-Requests-Quota / X-Rate-Limit-Time-Window-Seconds).


  • Endpoints that accept bulk requests may have specific limitations on the number of accepted parallel requests. For example, making multiple parallel upsert requests to /pricelists/{price_list_id}/records will result in a 429 error response – these limitations are documented at the operation level in the API Reference.

Respect platform limits

To promote stability and performance, BigCommerce sets store maximums on certain entities and values, and responds to API requests that would exceed them with a 403 Forbidden response.

For a list of limits, see Platform Limits in the Help Center.

Webhook events

Use webhooks to keep app data up-to-date

Rather than polling endpoints, get notified when updates occur by subscribing to webhooks.

User interface

Manage user session timeouts

Add BigCommerce’s JavaScript SDK to your single-click app’s front-end to prevent users from getting logged out of the control panel while using your app. To do so, reference the following script in your app’s client-side code:

To perform some action when a logout occurs, specify an onLogout callback:

      onLogout: callback

Streamline new user onboarding

  • If your app has a new user form, we recommend auto-filling input fields with data from the stores endpoint, which contains much of the info you need.
  • If your app doesn’t have an approval process for new users, consider automatically generating accounts for new stores that install your app.
  • If your app requires the user to sign in at launch, use the information BigCommerce sends to your callback URL to authenticate the user without asking for a username and password each time.
  • If you plan to share user testimonials, add a link to your full case study in the case studies field.


Consider hosting on Google Cloud Platform’s us-central1 region

BigCommerce hosts Google Cloud Platform in the us-central1 region; maximize performance by hosting in the same region.

Next steps


Sample apps


Blog posts