BigCommerce API Getting Started: Setup, Credentials, First Call (2026)

Getting started overview

Getting started with the BigCommerce API involves a series of steps designed to provide secure and authorized access to your store's data. The process typically begins with setting up a BigCommerce store, which provides the environment for API interactions. Following this, you'll generate the necessary API credentials, specifically a Store Hash and an Access Token, which act as authentication keys for your applications. These credentials are then used to make your first authenticated API request, confirming that your setup is correct and allowing you to begin developing integrations. BigCommerce offers comprehensive developer documentation to guide users through these initial steps and beyond.

The BigCommerce platform supports various types of API access, including storefront and server-to-server interactions. Storefront API access often utilizes OAuth 2.0 for user authentication, allowing applications to act on behalf of a user. For server-side applications, such as custom backend integrations or data synchronization tools, API tokens provide direct access to specific store resources. Understanding the distinction between these access methods is crucial for selecting the appropriate security model for your integration.

Quick start reference

The following table outlines the essential steps for initiating your BigCommerce API integration:

Create an account and get keys

To obtain the necessary API credentials, you must first have an active BigCommerce store. If you don't already have one, you can sign up for a 15-day free trial directly from the BigCommerce website. This trial provides a fully functional store environment where you can test your API integrations without commitment.

Creating an API account

Once your store is set up, follow these steps to generate your API credentials:

1. Log in to your BigCommerce store's control panel.
2. Navigate to Advanced Settings > API Accounts.
3. Click on Create API Account > Create V2/V3 API Token.
4. Provide a descriptive name for your API account (e.g., "My Integration App"). This helps identify the purpose of the credentials later.
5. Configure the API access scopes. These scopes define the permissions your API token will have. For your first request, it's common to grant read-only access to products or orders to ensure connectivity. For example, setting 'Catalog' and 'Orders' to 'read-only' is a good starting point. Be mindful of the principle of least privilege by only granting the necessary permissions.
6. Click Save.

Upon saving, BigCommerce will display your API Path (Store Hash), Access Token, and Client ID. It is critical to copy and securely store these credentials immediately, as the Access Token will only be shown once. The Store Hash is part of your API endpoint URL, and the Access Token is used in the X-Auth-Token header for authentication.

For example, a Store Hash might look like abcde12345, and an Access Token will be a long alphanumeric string. The Client ID is primarily used for OAuth-based applications, but it's good practice to store it as well.

Your first request

After obtaining your API credentials, you can make your first authenticated request to verify your setup. We'll use the BigCommerce V3 Catalog API to retrieve a list of products. This is a common starting point as it demonstrates basic read access.

Request components

• API Endpoint: https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products
• Headers:
  • X-Auth-Token: {{access_token}}
  • Content-Type: application/json
  • Accept: application/json
• Method: GET

Replace {{store_hash}} with your actual Store Hash and {{access_token}} with your Access Token.

Example using cURL

cURL is a widely available command-line tool for making HTTP requests and is excellent for quick tests. Open your terminal or command prompt and execute the following command:

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/YOUR_STORE_HASH/v3/catalog/products' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: YOUR_ACCESS_TOKEN'

Remember to replace YOUR_STORE_HASH and YOUR_ACCESS_TOKEN with your actual credentials. If successful, the API will return a JSON array of products from your store. An empty array "data": [] is a successful response if your store has no products yet. A 200 OK HTTP status code indicates a successful request.

Example using Node.js SDK

BigCommerce provides SDKs for several languages, simplifying API interactions. Here's an example using the Node.js SDK:

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

const bigCommerce = new BigCommerce({
  clientId: 'YOUR_CLIENT_ID', // Not strictly needed for server-to-server token auth, but good to include if you have it
  accessToken: 'YOUR_ACCESS_TOKEN',
  storeHash: 'YOUR_STORE_HASH',
  apiVersion: 'v3'
});

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

First, install the SDK: npm install node-bigcommerce. Then, replace the placeholder values with your credentials. This code will make a GET request to the /catalog/products endpoint and log the response to the console. The Node.js SDK handles the construction of the URL and headers automatically.

Common next steps

After successfully making your first API call, consider these next steps to deepen your integration:

• Explore More Endpoints: Review the BigCommerce API reference documentation to understand the full range of available endpoints for managing products, orders, customers, and other store resources. This will help you identify the specific data you need to interact with for your application.
• Implement Webhooks: For real-time updates, BigCommerce webhooks allow your application to receive notifications when specific events occur in your store (e.g., a new order is placed, a product is updated). This can significantly reduce the need for constant polling and improve application responsiveness.
• Utilize SDKs: While cURL is useful for testing, using one of the official BigCommerce SDKs (PHP, Node.js, Python, Ruby) can streamline development by abstracting HTTP requests, authentication, and error handling.
• OAuth for Public Apps: If you're building a public application that other BigCommerce merchants can install, you'll need to implement the OAuth flow. This allows merchants to grant your application permission to access their store data without sharing their direct API tokens. OAuth is a standard protocol for delegated authorization, as detailed by IETF RFC 6749.
• Error Handling: Implement robust error handling in your application. The BigCommerce API returns standard HTTP status codes and detailed JSON error messages to help diagnose issues. Understanding and handling these errors gracefully is crucial for reliable integrations.
• Rate Limiting: Be aware of BigCommerce API rate limits to avoid temporary blocks. Design your application to respect these limits, potentially using exponential backoff or queueing mechanisms for requests.

Troubleshooting the first call

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

• Incorrect Credentials: Double-check your Store Hash and Access Token. Ensure there are no leading or trailing spaces, and that they are copied exactly as provided by the BigCommerce control panel. The Access Token is case-sensitive.
• Invalid API Endpoint: Verify the URL. Ensure it correctly includes your Store Hash and the correct API version (e.g., /v3/catalog/products).
• Missing or Incorrect Headers: Confirm that the X-Auth-Token, Content-Type, and Accept headers are present and correctly formatted. The X-Auth-Token header should contain your Access Token directly, not prefixed with "Bearer" or similar.
• Insufficient Permissions (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 resource. Go back to your BigCommerce control panel, edit the API account, and ensure the required read/write permissions are granted for the specific API resources you are trying to access (e.g., 'Catalog' for products).
• Network Issues: Ensure your development environment has internet connectivity and is not blocked by a firewall from reaching api.bigcommerce.com.
• JSON Formatting Errors (for POST/PUT requests): If you are making a request that includes a request body (e.g., creating a product), ensure the JSON payload is valid and correctly structured according to the API documentation for that endpoint. You can use browser developer tools or online JSON validators to check syntax.
• Reviewing API Responses: Always examine the HTTP status code and the response body. BigCommerce API errors often contain descriptive messages that can pinpoint the exact problem. For example, a 404 Not Found might indicate an incorrect resource ID, while a 429 Too Many Requests points to rate limiting.
• Consulting Documentation: The BigCommerce developer documentation is an extensive resource. Look for the specific endpoint you're trying to use and review its requirements, request examples, and common error codes.