BigCommerce Catalog Management
Before writing code
Fetch live docs:
- Fetch
https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/brands for Catalog API reference
- Web-search
site:developer.bigcommerce.com catalog products variants options for product data model
- 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.
1---2name: bc-catalog3description: Work with BigCommerce catalog — products, variants, options, modifiers, categories, brands, metafields, images, and bulk operations. Use when managing product data programmatically or building catalog integrations.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-catalog7---89# BigCommerce Catalog Management1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/brands` for Catalog API reference152. Web-search `site:developer.bigcommerce.com catalog products variants options` for product data model163. Web-search `bigcommerce product options vs modifiers` for variant architecture1718## Product Data Model1920### Product Hierarchy2122```23Product24├── Options (define variant axes — e.g., Color, Size)25│ └── Option Values (Red, Blue, Small, Large)26├── Variants (specific combinations — Red/Small, Blue/Large)27│ ├── SKU, Price, Weight, Image28│ └── Inventory per variant29├── Modifiers (non-variant options — e.g., Engraving Text)30│ └── Modifier Values31├── Images (gallery images)32├── Videos33├── Custom Fields (key-value pairs shown on product page)34├── Metafields (hidden structured data for integrations)35└── Reviews36```3738### Products3940Core fields:41- `name`, `type`, `sku`, `description`42- `price`, `sale_price`, `retail_price`, `cost_price`43- `weight`, `width`, `height`, `depth`44- `is_visible`, `availability`, `condition`45- `categories` — array of category IDs46- `brand_id` — associated brand4748Product types: `physical`, `digital`4950### Options vs Modifiers5152| Feature | Options | Modifiers |53|---------|---------|-----------|54| Creates variants | Yes | No |55| Affects SKU | Yes | No |56| Affects inventory | Yes | No |57| Example | Color, Size | Gift wrapping, Engraving text |58| API path | `/products/{id}/options` | `/products/{id}/modifiers` |5960### Variants6162Each unique combination of option values creates a variant:63- Own `sku`, `price`, `weight`, `image_url`64- Own `inventory_level` and `inventory_warning_level`65- Identified by `id` and array of `option_values`66- Up to 600 variants per product (3 options × ~200 values)6768## Categories6970### Hierarchy7172Categories are tree-structured:73- `parent_id` — 0 for top-level, otherwise parent category ID74- `sort_order` — display order75- `is_visible` — visibility on storefront76- Can nest multiple levels deep7778### Category Assignment7980Products belong to one or more categories:81- Set via `categories` array on product82- A product can be in multiple categories83- Channel assignments can further control visibility per storefront8485## Brands8687Simple flat taxonomy:88- `name`, `page_title`, `meta_keywords`, `meta_description`89- `image_url` — brand logo90- Assigned to products via `brand_id`9192## Metafields9394### What They Are9596Key-value data storage for products, categories, brands, customers, and orders:97- **Not visible** on the storefront by default (unlike custom fields)98- Used for integration data (external IDs, sync timestamps, etc.)99- Namespaced: `app_id` + `namespace` + `key` = unique100- Permissions: `app_only`, `read`, `write`, `read_and_sf_access`101102### API103104- `POST /v3/catalog/products/{id}/metafields`105- Fields: `key`, `value`, `namespace`, `permission_set`, `description`106- Use `read_and_sf_access` permission to expose in GraphQL Storefront API107108## Images109110### Product Images111112- `POST /v3/catalog/products/{id}/images` — upload or reference by URL113- Fields: `image_url` or `image_file`, `is_thumbnail`, `sort_order`, `description`114- Multiple images per product (gallery)115- One designated as thumbnail116117### Variant Images118119Each variant can have its own image via `image_url` field on the variant.120121## Custom Fields122123Visible key-value pairs displayed on the product page:124- `name` — field label125- `value` — field value126- Displayed in the "Additional Information" section127- Managed via `/v3/catalog/products/{id}/custom-fields`128129## Bulk Operations130131### Batch Create/Update Products132133```134POST /v3/catalog/products135[136 { "name": "Product 1", "type": "physical", "price": 29.99, ... },137 { "name": "Product 2", "type": "physical", "price": 39.99, ... }138]139```140141### Batch Update142143```144PUT /v3/catalog/products145[146 { "id": 123, "price": 34.99 },147 { "id": 456, "price": 44.99 }148]149```150151### Batch Delete152153`DELETE /v3/catalog/products?id:in=123,456,789`154155## Querying Products156157### Filtering158159- `id:in=1,2,3` — by IDs160- `name:like=Widget` — name search161- `sku=ABC-123` — exact SKU match162- `categories:in=10,20` — by category163- `brand_id=5` — by brand164- `price:min=10&price:max=100` — price range165- `availability=available` — availability filter166- `is_visible=true` — visibility filter167- `include=images,variants,custom_fields` — include sub-resources168169### Pagination170171`?page=1&limit=50` — default 50, max 250 per page.172173## Best Practices174175- Use options for variant-defining attributes (color, size) and modifiers for everything else176- Use metafields for integration data — don't pollute custom fields177- Use `include=images,variants` to fetch sub-resources in one request178- Use batch endpoints for bulk imports/updates179- Respect rate limits — batch operations count as one request per batch180- Use webhooks (`store/product/updated`, `store/product/inventory/updated`) for real-time sync181- Set appropriate `permission_set` on metafields based on who needs access182183Fetch the BigCommerce Catalog API reference for exact endpoint paths, request schemas, and filter options before implementing.