DEV Community

Cover image for How to Use BigCommerce APIs: A Developer's Guide to E-commerce Integration
Preecha
Preecha

Posted on

How to Use BigCommerce APIs: A Developer's Guide to E-commerce Integration

TL;DR

BigCommerce APIs let you manage products, orders, customers, and store operations programmatically. Authenticate with API tokens for server-side integrations or OAuth for marketplace apps, call REST endpoints at api.bigcommerce.com, and use webhooks for real-time updates. Use Apidog to save API calls, validate responses, and share collections with your team.

Try Apidog today

Introduction

BigCommerce powers over 60,000 online stores. Common integration tasks include inventory synchronization, order processing, customer management, and payment handling.

BigCommerce provides three API types:

  • Storefront API for headless commerce experiences
  • Management API for backend operations
  • Payments API for transactions

Most integrations use the Management API to manage products, orders, customers, and store operations.

This guide focuses on the implementation work most integrations need: authentication, products, orders, customers, webhooks, and API testing.

By the end, you will be able to:

  • Set up BigCommerce authentication
  • Manage products, variants, and inventory
  • Process orders and customer data
  • Configure webhooks for real-time events
  • Test and document integrations with Apidog

Authentication: Get access to a store

Choose the authentication method based on your integration type.

Method 1: API tokens for custom integrations

Use an API token when a script or service connects to a single store.

  1. Open the BigCommerce store admin.
  2. Go to Settings → API Accounts → Create API Account.
  3. Choose V3/V2 API Token.
  4. Select only the scopes your integration needs, such as Products, Orders, or Customers.
  5. Save the credentials securely.

You receive:

  • Store URL: mystore.mybigcommerce.com
  • Access token: abc123def456...
  • Client ID: abc123...
  • Client secret: xyz789...

Make a test request:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

Replace {store-hash} with your store hash. It appears in the API URL after /stores/ and is also visible in the store admin URL.

Method 2: OAuth for marketplace apps

Use OAuth when building an app that merchants install through the BigCommerce marketplace.

The OAuth flow is:

  1. A merchant clicks Install.
  2. BigCommerce redirects to your callback URL with an authorization code.
  3. Your server exchanges the code for an access token.
  4. Store the token and store hash for future API requests.

Exchange the authorization code:

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})

const { access_token, context } = await response.json()

// Use access_token for API calls.
// context contains the store_hash.
Enter fullscreen mode Exit fullscreen mode

Use the returned token in Management API requests:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

Products and catalog management

Use the V3 Catalog API to manage products, variants, categories, and brands.

List products 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Example response:

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Create a product 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium cotton blend hoodie",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}
Enter fullscreen mode Exit fullscreen mode

Update product variants

Products with options such as size and color use variants. Each variant can have its own SKU, price, and inventory level.

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Black"
    },
    {
      "option_display_name": "Size",
      "label": "Medium"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Manage inventory

Update inventory for a product:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

Or update inventory for a specific variant:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Orders and fulfillment

Use the Orders V2 API to retrieve orders, update statuses, and create shipments.

List orders 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Example response:

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Get order details and line items

Get an order:

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Get the products in that order:

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Update an order status 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "status_id": 12
}
Enter fullscreen mode Exit fullscreen mode

Common status IDs:

  • 0: Incomplete
  • 11: Awaiting Fulfillment
  • 12: Completed
  • 5: Cancelled
  • 4: Refunded

Create a shipment

Create a shipment after your fulfillment system processes the order:

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Customers and segmentation

Use the Customers V3 API for customer profiles, addresses, and customer groups.

List customers 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Example response:

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Create a customer 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}
Enter fullscreen mode Exit fullscreen mode

Update a customer 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Webhooks for real-time updates

Webhooks notify your application when store events occur. They let you react to events without polling the API.

Create a webhook 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

Common webhook scopes:

  • store/order/created: New order placed
  • store/order/updated: Order status changed
  • store/order/archived: Order archived
  • store/product/created: Product added
  • store/product/updated: Product modified
  • store/product/deleted: Product removed
  • store/customer/created: New customer
  • store/inventory/updated: Stock changed

Verify webhook signatures

BigCommerce signs webhooks so you can verify that incoming requests are legitimate.

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // Process the webhook event.
  console.log('Order created:', req.body.data.id)

  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Testing BigCommerce APIs with Apidog

BigCommerce requests require consistent headers, authentication, and response validation. Save requests in Apidog collections so your team can test the same flows against staging and production stores.

Image

1. Create store environments

Create an environment for each store so requests use variables instead of hard-coded credentials.

# Production Store
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123
Enter fullscreen mode Exit fullscreen mode 
# Staging Store
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

Use the BASE_URL variable in your requests:

GET {{BASE_URL}}/v3/catalog/products
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

2. Add pre-request scripts

Add authentication headers automatically:

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})

pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})
Enter fullscreen mode Exit fullscreen mode

3. Validate API responses

Add tests that verify required product fields and pagination metadata:

pm.test('Products have required fields', () => {
  const response = pm.response.json()

  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('Pagination works', () => {
  const response = pm.response.json()

  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})
Enter fullscreen mode Exit fullscreen mode

Common errors and fixes

401 Unauthorized

Cause: The access token is missing or invalid.

Fix:

  • Verify that the X-Auth-Token header is present.
  • Confirm that the token has not been revoked.
  • Check that the API account has the required scopes.

403 Forbidden

Cause: The token is valid but does not have the required scope.

Fix:

  • Review API account permissions.
  • Add the missing Products, Orders, Customers, or other scope.
  • Generate a new token with expanded permissions.

404 Not Found

Cause: The endpoint is incorrect or the resource does not exist.

Fix:

  • Verify the store hash.
  • Check whether the endpoint uses v2 or v3.
  • Confirm that the resource ID exists.

429 Too Many Requests

Cause: You exceeded the endpoint rate limit.

BigCommerce allows different limits per endpoint. Products allow 10,000 requests per hour, while Orders allow 30,000 requests per hour. Check the X-Rate-Limit-Remaining response header and add backoff handling.

async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()

    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')

      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 Unprocessable Entity

Cause: A validation error exists in the request body.

Check the response body for field-level details:

{
  "errors": {
    "price": "Price must be greater than zero",
    "sku": "SKU already exists"
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternatives and comparisons

Feature BigCommerce Shopify WooCommerce
API versioning V2 and V3 REST and GraphQL REST
Rate limits 10K–30K/hour 2/min (leaky bucket) Depends on hosting
Webhooks Yes Yes Yes (plugin)
GraphQL No Yes No
SDK quality Good Excellent PHP only
Multi-store Yes No No

BigCommerce’s V3 API is more consistent than Shopify’s fragmented approach, while Shopify’s GraphQL API provides more flexibility for complex queries.

Real-world use cases

Multi-channel inventory sync

A brand selling through BigCommerce, Amazon, and physical stores can use the Products API to synchronize inventory levels across channels and reduce overselling. Test inventory update requests before each deployment.

Order automation

A subscription box company can use order webhooks to trigger fulfillment when orders are created. Its integration can create warehouse pick lists and update shipment tracking through the Orders API.

Customer segmentation

An e-commerce site can use the Customers API to group buyers based on purchase history. A scheduled job can add VIP customers to a group with exclusive pricing.

Conclusion

You now have the core implementation patterns for a BigCommerce integration:

  • Use API tokens for single-store integrations and OAuth for marketplace apps.
  • Use the V3 Catalog API for products and variants.
  • Use the V2 Orders API for order processing and fulfillment.
  • Use the V3 Customers API for customer data.
  • Use webhooks for real-time store events.
  • Save and validate requests with Apidog before deploying changes.

Next steps:

  1. Create an API account in your BigCommerce store.
  2. Make a request to list products.
  3. Create an order webhook.
  4. Save the requests in an Apidog collection.
  5. Build and test your integration against a staging store.

FAQ

What is the difference between V2 and V3 APIs?

V3 is the newer and more consistent API. Use it for products, categories, brands, and customers. V2 handles orders, which have not been migrated yet. Most integrations use both versions.

How do I get my store hash?

Your store hash appears in the BigCommerce admin URL:

https://store-abc123.mybigcommerce.com/manage
Enter fullscreen mode Exit fullscreen mode

In this example, abc123 is the store hash. It is also available in API account settings.

Can I use the API on a trial store?

Yes. BigCommerce trial stores have full API access, making them useful for development and testing before going live.

What is the rate limit for API calls?

Limits depend on the endpoint. Products allow 10,000 requests per hour, while Orders allow 30,000 requests per hour. Check X-Rate-Limit-Remaining in API responses to monitor the current limit.

How do I handle pagination?

Use the page and limit query parameters. The default limit is 50. Check meta.pagination in each response and continue until you fetch every page.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )

  const data = await response.json()
  allProducts.push(...data.data)

  if (page >= data.meta.pagination.total_pages) break

  page++
}
Enter fullscreen mode Exit fullscreen mode

Can I upload product images through the API?

Yes. Use the product images endpoint:

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

How do I handle currency and multiple stores?

BigCommerce stores have a base currency. Multi-currency is handled at the storefront level rather than through the API. For multiple stores, create separate API accounts and use separate environments in Apidog.

What happens if my webhook endpoint is down?

BigCommerce retries failed webhooks with exponential backoff. After five failures over 24 hours, BigCommerce disables the webhook. Monitor webhook endpoints and alert on failures.

Top comments (0)