DEV Community

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

Posted on • Originally published at apidog.com

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 using API tokens (server-side) or OAuth (apps), call REST endpoints at api.bigcommerce.com, and use webhooks for real-time updates. For testing, leverage Apidog to organize API calls, validate responses, and collaborate with your team.

Introduction

BigCommerce powers 60,000+ online stores, each needing custom integrations—inventory sync, order processing, customer management, and more. Their APIs enable automation for these workflows.

Try Apidog today

BigCommerce exposes three main API types:

  • Storefront API: Headless commerce
  • Management API: Backend operations (most common)
  • Payments API: Transactions

Most integrations use the Management API, which covers products, orders, customers, and backend operations. While the APIs are approachable, documentation can be scattered. This guide focuses on actionable steps for products, orders, customers, and webhooks, covering authentication, common patterns, and integration testing.

💡 Tip: Apidog streamlines API design, testing, and documentation. Save requests, use environments, and validate responses—catching issues before they impact production.

Test your BigCommerce APIs with Apidog—free.

By the end of this guide, you’ll be able to:

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

Authentication: Getting Access to Your Store

BigCommerce supports two authentication flows:

Method 1: API Tokens (Custom Integrations)

Use API tokens for scripts/services targeting a single store.

Steps to create an API account:

  1. Go to your store’s admin panel
  2. Navigate to: Settings → API Accounts → Create API Account
  3. Choose “V3/V2 API Token”
  4. Select required scopes (Products, Orders, Customers, etc.)
  5. Save the credentials

You’ll receive:

  • Store URL: mystore.mybigcommerce.com
  • Access Token: abc123def456...
  • Client ID: abc123...
  • Client Secret: xyz789...

Sample API call:

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

Get your store-hash from your admin URL or API account settings.

Method 2: OAuth (Marketplace Apps)

Use OAuth for apps distributed via the BigCommerce marketplace.

OAuth flow:

  1. User installs your app
  2. BigCommerce redirects to your callback with an auth code
  3. Your backend exchanges the code for an access token
  4. Store the token for future API calls

Exchange code for token:

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();
// access_token: use in API calls
// context: contains store_hash
Enter fullscreen mode Exit fullscreen mode

Use the token:

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

The V3 Catalog API manages 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

{
  "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

For products with options (size, color):

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

{
  "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 product inventory:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

Or for a variant:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Orders and Fulfillment

The Orders V2 API manages order creation, updates, and fulfillment.

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 

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

Get Order Products 

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

Update Order Status 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "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 (Fulfillment) 

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "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

The Customers V3 API manages customer data, addresses, and 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

{
  "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 Customer 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Webhooks for Real-Time Updates

Webhooks send POSTs to your endpoints when store events occur.

Create a Webhook 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

Available scopes:

  • store/order/created – Order placed
  • store/order/updated – 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 – Inventory changed

Verify Webhook Signatures

BigCommerce signs webhooks for authenticity:

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
  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 APIs require consistent headers and authentication. Apidog streamlines this process.

Apidog Screenshot

1. Environment Setup

Define environments for each store:

# Production Store
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

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

2. Pre-request Scripts

Auto-inject headers:

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 Responses

Check required product fields and pagination:

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

Test BigCommerce APIs with Apidog — free.

Common Errors and Fixes

401 Unauthorized

Cause: Invalid/missing access token.

Fix:

  1. Ensure X-Auth-Token is set
  2. Verify token validity
  3. Check API account scopes

403 Forbidden

Cause: Insufficient token scope.

Fix:

  1. Review API account permissions
  2. Add missing scopes
  3. Generate a new token if necessary

404 Not Found

Cause: Wrong endpoint or missing resource.

Fix:

  1. Verify store-hash
  2. Check API version (v2 vs v3)
  3. Confirm resource ID exists

429 Too Many Requests

Cause: Rate limit exceeded.

Fix: Products: 10,000/hr. Orders: 30,000/hr. Check X-Rate-Limit-Remaining and implement backoff:

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(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 Unprocessable Entity

Cause: Request body validation error.

Fix: Inspect response for 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/hr 2/min (leaky bucket) Depends on host
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 consistent, while Shopify’s GraphQL API offers flexibility for complex queries.

Real-World Use Cases

  • Multi-channel inventory sync: Sync inventory across BigCommerce, Amazon, and POS using the Products API. Validate endpoints in Apidog before each deployment.
  • Order automation: Use webhooks to trigger fulfillment workflows. Update tracking via Orders API. Automate warehouse pick lists.
  • Customer segmentation: Segment customers by purchase history using the Customers API. Assign VIPs to special pricing groups via scheduled jobs.

Conclusion

Key takeaways:

  • Use API tokens for single-store integrations; OAuth for apps
  • V3 Catalog API manages products/variants
  • V2 Orders API handles order processing
  • V3 Customers API for customer data
  • Webhooks deliver real-time updates
  • Test and document with Apidog for reliable integrations

Next steps:

  1. Create an API account in BigCommerce
  2. Make your first API call (list products)
  3. Set up an order creation webhook
  4. Save API calls in Apidog
  5. Build your integration

Test BigCommerce APIs with Apidog — free.

FAQ

What’s the difference between V2 and V3 APIs?

V3 is newer and more consistent—use for products, categories, brands, customers. V2 still handles orders.

How do I get my store hash?

Find it in your admin URL: https://store-abc123.mybigcommerce.com/manage (abc123 is your store hash).

Can I use the API on a trial store?

Yes. Trial stores have full API access—ideal for development/testing.

What’s the rate limit for API calls?

Products: 10,000/hr. Orders: 30,000/hr. Check X-Rate-Limit-Remaining in responses.

How do I handle pagination?

Use page and limit query parameters. Default is 50 per page. Check meta.pagination for total pages:

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 via API?

Yes. Use the images endpoint:

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

How do I handle currency and multi-store?

Each store has a base currency. Multi-currency is storefront-level, not API. For multiple stores, use separate API accounts and Apidog environments.

What happens if my webhook endpoint is down?

BigCommerce retries failed webhooks with exponential backoff. After 5 failures in 24 hours, the webhook is disabled. Monitor and alert on failures.

Top comments (0)