orcaqubits/bc-catalog

BigCommerce Catalog Management

Before writing code

Fetch live docs:

1. Fetch https://developer.bigcommerce.com/docs/rest-catalog for Catalog API reference
2. Web-search site:developer.bigcommerce.com catalog products variants options for product data model
3. Web-search bigcommerce product options vs modifiers for variant architecture

Product Data Model

Product Hierarchy

Product
├── Options (define variant axes — e.g., Color, Size)
│   └── Option Values (Red, Blue, Small, Large)
├── Variants (specific combinations — Red/Small, Blue/Large)
│   ├── SKU, Price, Weight, Image
│   └── Inventory per variant
├── Modifiers (non-variant options — e.g., Engraving Text)
│   └── Modifier Values
├── Images (gallery images)
├── Videos
├── Custom Fields (key-value pairs shown on product page)
├── Metafields (hidden structured data for integrations)
└── Reviews

Products

Core fields:

• name, type, sku, description
• price, sale_price, retail_price, cost_price
• weight, width, height, depth
• is_visible, availability, condition
• categories — array of category IDs
• brand_id — associated brand

Product types: physical, digital

Options vs Modifiers

| Feature | Options | Modifiers | |---------|---------|-----------| | Creates variants | Yes | No | | Affects SKU | Yes | No | | Affects inventory | Yes | No | | Example | Color, Size | Gift wrapping, Engraving text | | API path | /products/{id}/options | /products/{id}/modifiers |

Variants

Each unique combination of option values creates a variant:

• Own sku, price, weight, image_url
• Own inventory_level and inventory_warning_level
• Identified by id and array of option_values
• Up to 600 variants per product (3 options × ~200 values)

Categories

Hierarchy

Categories are tree-structured:

• parent_id — 0 for top-level, otherwise parent category ID
• sort_order — display order
• is_visible — visibility on storefront
• Can nest multiple levels deep

Category Assignment

Products belong to one or more categories:

• Set via categories array on product
• A product can be in multiple categories
• Channel assignments can further control visibility per storefront

Brands

Simple flat taxonomy:

• name, page_title, meta_keywords, meta_description
• image_url — brand logo
• Assigned to products via brand_id

Metafields

What They Are

Key-value data storage for products, categories, brands, customers, and orders:

• Not visible on the storefront by default (unlike custom fields)
• Used for integration data (external IDs, sync timestamps, etc.)
• Namespaced: app_id + namespace + key = unique
• Permissions: app_only, read, write, read_and_sf_access

API

• POST /v3/catalog/products/{id}/metafields
• Fields: key, value, namespace, permission_set, description
• Use read_and_sf_access permission to expose in GraphQL Storefront API

Images

Product Images

• POST /v3/catalog/products/{id}/images — upload or reference by URL
• Fields: image_url or image_file, is_thumbnail, sort_order, description
• Multiple images per product (gallery)
• One designated as thumbnail

Variant Images

Each variant can have its own image via image_url field on the variant.

Custom Fields

Visible key-value pairs displayed on the product page:

• name — field label
• value — field value
• Displayed in the "Additional Information" section
• Managed via /v3/catalog/products/{id}/custom-fields

Bulk Operations

Batch Create/Update Products

POST /v3/catalog/products
[
  { "name": "Product 1", "type": "physical", "price": 29.99, ... },
  { "name": "Product 2", "type": "physical", "price": 39.99, ... }
]

Batch Update

PUT /v3/catalog/products
[
  { "id": 123, "price": 34.99 },
  { "id": 456, "price": 44.99 }
]

Batch Delete

DELETE /v3/catalog/products?id:in=123,456,789

Querying Products

Filtering

• id:in=1,2,3 — by IDs
• name:like=Widget — name search
• sku=ABC-123 — exact SKU match
• categories:in=10,20 — by category
• brand_id=5 — by brand
• price:min=10&price:max=100 — price range
• availability=available — availability filter
• is_visible=true — visibility filter
• include=images,variants,custom_fields — include sub-resources

Pagination

?page=1&limit=50 — default 50, max 250 per page.

Best Practices

• Use options for variant-defining attributes (color, size) and modifiers for everything else
• Use metafields for integration data — don't pollute custom fields
• Use include=images,variants to fetch sub-resources in one request
• Use batch endpoints for bulk imports/updates
• Respect rate limits — batch operations count as one request per batch
• Use webhooks (store/product/updated, store/product/inventory/updated) for real-time sync
• Set appropriate permission_set on metafields based on who needs access

Fetch the BigCommerce Catalog API reference for exact endpoint paths, request schemas, and filter options before implementing.