BigCommerce Getting Started: API Keys & First Request (2026)

Getting started overview

To begin developing with BigCommerce, the initial steps involve setting up a trial store, generating API credentials, and making an authenticated call to one of the platform's endpoints. This guide focuses on the foundational process required to establish connectivity and execute a basic operation, such as retrieving a list of products or categories. BigCommerce provides a comprehensive API primarily based on REST principles, allowing for programmatic management of various aspects of an online store, including products, orders, customers, and more.

The BigCommerce API supports operations for storefront data, order processing, customer management, and integrating with third-party applications. Developers interact with the API using standard HTTP methods (GET, POST, PUT, DELETE) and JSON payloads for data exchange. Authentication typically relies on OAuth 2.0 for storefront access and API tokens for control panel access, ensuring secure communication between client applications and the BigCommerce platform.

Before making any API calls, it is necessary to obtain the required API credentials, which include a Client ID, an Access Token, and the Store Hash. These credentials are generated within the BigCommerce control panel after creating a store. The Store Hash is a unique identifier for your BigCommerce store, crucial for directing API requests to the correct instance. The Client ID and Access Token are used together to authenticate your application's requests, ensuring that only authorized applications can interact with your store's data.

Quick reference table

Create an account and get keys

The initial step for any developer is to create a BigCommerce store. BigCommerce offers a 15-day free trial, which provides full access to the platform's features, including the developer tools and API access. During the sign-up process, you will be prompted to enter basic store information, and upon completion, you will gain access to your BigCommerce control panel.

Once your trial store is active, navigate to the BigCommerce control panel to generate your API credentials. These credentials are essential for authenticating your API requests. Follow these steps:

1. Log into your BigCommerce control panel.
2. Go to Advanced Settings > API Accounts.
3. Click Create API Account > Create V2/V3 API Token.
4. Provide a descriptive name for your API account (e.g., "My Application Integration").
5. Configure the API scopes. This defines the permissions your API account will have. For a "Getting Started" request, you might grant read access to products and categories. It is recommended to apply the principle of least privilege, granting only the necessary permissions.
6. Click Save.

Upon saving, BigCommerce will display your API credentials: a Client ID, an Access Token, and your Store Hash. It is critical to copy and store these values securely immediately, as the Access Token will only be displayed once for security reasons. The Store Hash is embedded in your store's URL (e.g., https://store-[store_hash].mybigcommerce.com/) and is also provided when you create the API account. These three pieces of information are necessary for constructing authenticated API requests.

For example, if you want to read product information, you would grant read permissions for the "Catalog" scope. If you need to update orders, you would grant modify permissions for the "Orders" scope. Understanding BigCommerce API authentication is key to secure and effective integration.

Your first request

With your API credentials in hand, you can now make your first authenticated request to the BigCommerce API. A common initial request is to retrieve a list of products. This demonstrates successful authentication and interaction with the platform.

The base URL for BigCommerce API requests follows this format: https://api.bigcommerce.com/stores/{store_hash}/v3/. Your specific {store_hash} will be the one you obtained when creating your API account.

To retrieve products, you would append catalog/products to the base URL. The request requires two headers for authentication:

• X-Auth-Client: Your Client ID
• X-Auth-Token: Your Access Token

Here's an example using cURL to fetch the first few products from your store:

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products' \
  --header 'X-Auth-Client: {client_id}' \
  --header 'X-Auth-Token: {access_token}' \
  --header 'Accept: application/json'

Replace {store_hash}, {client_id}, and {access_token} with your actual credentials. If successful, the API will return a JSON array of products, demonstrating that your authentication is correctly configured and your request was processed by BigCommerce.

Alternatively, you can use one of the officially supported SDKs for Node.js, PHP, Python, or Ruby. These SDKs abstract away the HTTP request details and handle authentication, simplifying development. For example, using the Node.js SDK, the process might look like this:

const BigCommerce = require('node-bigcommerce');

const bigCommerce = new BigCommerce({
  clientId: '{client_id}',
  accessToken: '{access_token}',
  storeHash: '{store_hash}',
  apiVersion: 'v3'
});

bigCommerce.get('/catalog/products')
  .then(data => console.log(data))
  .catch(err => console.error(err));

Remember to install the appropriate SDK package (e.g., npm install node-bigcommerce) before running the code. The BigCommerce API Reference provides detailed examples for each endpoint.

Common next steps

After successfully making your first API call, several common next steps can further your integration with BigCommerce:

1. Explore other API endpoints: Review the BigCommerce API reference to understand the full range of available endpoints. This includes managing orders, customers, categories, webhooks, and more. Understanding the BigCommerce API capabilities is crucial for building comprehensive integrations.
2. Implement webhooks: For real-time event notifications (e.g., new order created, product updated), BigCommerce webhooks are essential. Webhooks allow your application to receive push notifications when specific events occur in your store, reducing the need for constant polling. For general information on webhooks, the MDN Web Docs on Webhooks offers a good overview.
3. Develop with SDKs: If you are working with Node.js, PHP, Python, or Ruby, consider using the official BigCommerce SDKs. They simplify API interactions, handle authentication, and provide a more idiomatic way to interact with the platform.
4. Error handling and logging: Implement robust error handling in your application to gracefully manage API rate limits, invalid requests, and server errors. Logging API responses and errors is also vital for debugging and monitoring your integration.
5. OAuth 2.0 for storefront apps: If you are building an application that interacts with storefront data (e.g., a custom checkout experience or a customer loyalty program), you will need to implement OAuth 2.0 for user authentication and authorization. This is distinct from the API token authentication used for control panel access.
6. Performance optimization: As your integration scales, consider strategies for optimizing API performance, such as pagination for large data sets, selective field retrieval, and caching frequently accessed static data.
7. Security best practices: Always follow security best practices, including protecting your API credentials, validating incoming data, and adhering to BigCommerce's security guidelines. Regularly review and update the scopes granted to your API accounts.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for BigCommerce API requests:

• Incorrect Credentials: Double-check your Client ID, Access Token, and Store Hash. Ensure there are no typos or leading/trailing spaces. Remember that the Access Token is only shown once upon creation, so if you missed it, you might need to generate a new API account.
• Invalid Store Hash: Verify that the Store Hash in your URL (https://api.bigcommerce.com/stores/{store_hash}/v3/) matches the one provided in your API account details. The Store Hash is a unique identifier for your store.
• Missing or Incorrect Headers: Ensure that both X-Auth-Client and X-Auth-Token headers are correctly set in your request. The header names are case-sensitive.
• Insufficient API Scopes: If you receive a 403 Forbidden error, it likely means your API account does not have the necessary permissions (scopes) to access the requested endpoint. Return to your BigCommerce control panel (Advanced Settings > API Accounts), edit your API account, and grant the appropriate read/write permissions for the resources you are trying to access (e.g., 'Catalog' for products, 'Orders' for orders). Always grant the minimum necessary permissions.
• Incorrect Endpoint Path: Verify the API endpoint path is correct (e.g., /catalog/products for fetching products). Consult the BigCommerce API reference for exact paths and parameters.
• JSON Parsing Errors: If you are sending a POST or PUT request with a request body, ensure the body is valid JSON and that the Content-Type: application/json header is set.
• Network Issues: Check your internet connection. If you are behind a corporate firewall, ensure that access to api.bigcommerce.com is not blocked.
• Rate Limiting: BigCommerce enforces API rate limits to prevent abuse and ensure stability. If you make too many requests too quickly, you might receive a 429 Too Many Requests error. Implement retry logic with exponential backoff if you anticipate hitting these limits.
• Review Error Messages: BigCommerce API responses often include detailed error messages within the JSON payload. Carefully read these messages, as they frequently provide specific clues about what went wrong.