← Back to EcomCentral
BIGCOMMERCE REST API v2 / v3

BigCommerce Setup Guide

Connect your BigCommerce store to EcomCentral using a store-level API account with X-Auth-Token authentication.

Prerequisites

ℹ️ BigCommerce uses store-level API accounts authenticated via the X-Auth-Token HTTP header. No OAuth user flow is needed. The store hash appears in your API base URL: https://api.bigcommerce.com/stores/{store_hash}/v2/

Getting Your API Credentials

  1. Log in to your BigCommerce control panel
  2. Go to Settings → API → Store-level API accounts
  3. Click Create API account → Create V2/V3 API token
  4. Set a name, then under OAuth Scopes enable: Orders (Modify) and Products (Modify)
  5. Click Save — copy the Access Token and Store Hash from the credentials panel
  6. In EcomCentral, add a new BigCommerce connection with both values
  7. Click ⚡ Test — should return your store name, domain, and plan

Credentials Reference

KeyRequiredDescriptionExample
store_hash Required Short alphanumeric store identifier from the API base URL abc123xyz
access_token Required API access token from Settings → API → Store-level API accounts xyzabc123…
✅ Alternative key names: storeHash or hash for the store hash; accessToken or token for the access token.

API Endpoints Used

OperationAPI verMethodEndpoint
Test connectionV2GET/v2/store
List ordersV2GET/v2/orders?page=P&limit=N&sort=date_created:desc
Order detailV2GET/v2/orders/{id}
Order line itemsV2GET/v2/orders/{id}/products
Order shipping addressesV2GET/v2/orders/{id}/shippingaddresses
Add tracking (shipment)V2POST/v2/orders/{id}/shipments
Order countV2GET/v2/orders/count
List productsV3GET/v3/catalog/products?page=P&limit=N
Product detail + variantsV3GET/v3/catalog/products/{id}?include=variants,images
Update stockV3PUT/v3/catalog/products/{id} with { inventory_level: N }
ℹ️ BigCommerce mixes two API versions: V2 for orders (bare JSON arrays, no pagination envelope) and V3 for catalog products ({ data:[...], meta:{pagination:{total}} } envelope). EcomCentral handles both transparently.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Order ID, date, status, total + currency
View order detail✅Line items, billing address, shipping addresses, payment method
Add tracking / create shipment✅Tracking number + carrier; auto-resolves first shipping address. Optional tracking URL.
View products (paginated)✅SKU, name, price, inventory level (V3 catalog)
View product detail + variants✅Variants with SKU, options, price, stock; images
Update stock quantity✅PUT /v3/catalog/products/{id} with inventory_level
Test connection✅Returns store name, domain, plan, currency
⚠️ Stock update requires inventory tracking enabled. If the product has inventory_tracking: "none", the inventory_level field is ignored by BigCommerce even if the API call succeeds. Enable tracking in the product settings first.

Troubleshooting

✕ 401 Unauthorized

The access_token is invalid or the API account was deleted. Regenerate the token in Settings → API → Store-level API accounts and update via Rotate Keys.

✕ 403 Forbidden on shipment creation

Ensure the API account has Orders: Modify scope. Read-only orders scope cannot create shipments. Note: a trailing slash on the endpoint URL causes 403 — EcomCentral avoids this.

✕ Stock update has no effect

The product's inventory_tracking must be set to "product" (not "none") for inventory_level writes to take effect. Change this in the BigCommerce control panel under the product's Inventory tab.

✕ Shipment creation fails with "No shipping address"

BigCommerce requires an order_address_id when creating a shipment. EcomCentral automatically resolves the first shipping address on the order. If the order has no shipping address (e.g. digital product orders), shipment creation is not possible via the API.