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`:
```json
{
  "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

```json
{
  "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.