orcaqubits/bc-api-rest

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

| Version | Base URL | Notes | |---------|----------|-------| | V2 | /stores/{hash}/v2/ | Legacy — orders, some customer endpoints | | V3 | /stores/{hash}/v3/ | Modern — most resources, JSON:API-like |

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

| Endpoint | Methods | Description | |----------|---------|-------------| | /v3/catalog/products | GET, POST, PUT, DELETE | Products CRUD | | /v3/catalog/products/{id}/variants | GET, POST, PUT, DELETE | Product variants | | /v3/catalog/products/{id}/images | GET, POST, PUT, DELETE | Product images | | /v3/catalog/categories | GET, POST, PUT, DELETE | Categories | | /v3/catalog/brands | GET, POST, PUT, DELETE | Brands | | /v3/catalog/products/channel-assignments | GET, PUT | Channel product assignments |

Orders (V2 — legacy but current)

| Endpoint | Methods | Description | |----------|---------|-------------| | /v2/orders | GET, POST, PUT | Orders | | /v2/orders/{id}/products | GET | Order line items | | /v2/orders/{id}/shipments | GET, POST, PUT | Shipments | | /v2/orders/{id}/shipping_addresses | GET | Shipping addresses |

Customers

| Endpoint | Methods | Description | |----------|---------|-------------| | /v3/customers | GET, POST, PUT, DELETE | Customers CRUD | | /v3/customers/addresses | GET, POST, PUT, DELETE | Customer addresses | | /v3/customers/attribute-values | GET, PUT, DELETE | Customer attributes |

Other Key Endpoints

| Endpoint | Description | |----------|-------------| | /v3/channels | Storefronts/channels | | /v3/carts | Server-side cart | | /v3/checkouts | Server-side checkout | | /v3/payments | Payment processing | | /v3/content/widgets | Widgets | | /v3/themes | Theme management | | /v3/hooks | Webhooks | | /v3/storefront/api-token | Storefront API tokens |

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

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No Content (successful delete) | | 400 | Bad Request (invalid parameters) | | 401 | Unauthorized (invalid token) | | 403 | Forbidden (insufficient scope) | | 404 | Not Found | | 409 | Conflict (duplicate resource) | | 422 | Unprocessable Entity (validation error) | | 429 | Rate Limited | | 500 | Internal Server Error |

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.