BigCommerce REST API Development

Before writing code

Fetch live docs:

1. Fetch https://developer.bigcommerce.com/docs/rest for REST API overview
2. Web-search site:developer.bigcommerce.com rest-management for Management API reference
3. Web-search bigcommerce api v3 rate limits pagination for rate limit details

API Architecture

Two API Versions

V3 is preferred for all new development. V2 is still required for some resources that haven't been migrated.

Base URL

https://api.bigcommerce.com/stores/{store_hash}/v3/

The store_hash is found in the API Path when creating credentials.

Authentication

API Account Tokens

For server-to-server requests:

X-Auth-Token: {access_token}
Content-Type: application/json
Accept: application/json

OAuth Tokens

For apps using the OAuth flow — same header format, token obtained during installation.

Scopes

Tokens have scopes that control access:

• store_v2_products / store_v2_products_read_only
• store_v2_orders / store_v2_orders_read_only
• store_v2_customers / store_v2_customers_read_only
• store_v2_content, store_v2_marketing, store_v2_information
• store_themes_manage, store_cart, store_checkout

Key V3 Endpoints

Catalog

Orders (V2 — legacy but current)

Customers

Other Key Endpoints

Pagination

V3 Pagination

Query parameters:

• page — page number (default 1)
• limit — items per page (default 50, max 250)

Response includes meta.pagination:

{
  "data": [...],
  "meta": {
    "pagination": {
      "total": 250,
      "count": 50,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 5
    }
  }
}

V2 Pagination

Uses Link header with rel="next" and rel="previous".

Filtering

V3 Query Parameters

• id:in=1,2,3 — filter by multiple IDs
• name:like=Widget%25 — partial name match
• date_modified:min=2024-01-01 — date range
• include=images,variants — include sub-resources
• sort=name / sort=-date_created — sort ascending/descending
• include_fields=name,price — select specific fields
• exclude_fields=description — exclude specific fields

Rate Limiting

Default Limits

Typically 450 requests per 30-second window (varies by plan):

• Standard: 150 requests/30s
• Plus: 200 requests/30s
• Pro: 400 requests/30s
• Enterprise: 450+ requests/30s

Headers

• X-Rate-Limit-Requests-Left — remaining requests in window
• X-Rate-Limit-Time-Reset-Ms — ms until window resets
• X-Rate-Limit-Requests-Quota — total requests allowed
• HTTP 429 when exceeded — retry after reset

Best Practices for Rate Limits

• Check X-Rate-Limit-Requests-Left before batches
• Implement exponential backoff on 429 responses
• Use batch endpoints where available
• Cache responses that don't change frequently

Batch Operations

Some V3 endpoints support batch operations:

• POST /v3/catalog/products — create multiple products (array)
• PUT /v3/catalog/products — update multiple products (array)
• DELETE /v3/catalog/products?id:in=1,2,3 — delete multiple

Error Handling

Response Format

{
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
  "errors": {
    "name": "Product name is required"
  }
}

Common Status Codes

Best Practices

• Use V3 for all new development — V2 only where V3 equivalent doesn't exist
• Include Accept: application/json and Content-Type: application/json headers
• Use include to fetch sub-resources in one request (avoid N+1)
• Use include_fields / exclude_fields to minimize response size
• Implement rate limit handling with exponential backoff
• Use batch endpoints for bulk operations
• Cache read-heavy data that changes infrequently
• Handle 429 responses gracefully — don't retry immediately

Fetch the BigCommerce REST API reference for exact endpoint paths, query parameters, request/response schemas, and current rate limits before implementing.