Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 28 ยท REST APIs

The Catalog API (V3)

Work with the BigCommerce Catalog API V3: products, variants, options, modifiers, categories, brands, custom fields, pagination, includes, filters and batch writes.

The Catalog API is the part of BigCommerce you will call most often. It manages what a shop sells: products and their variants, options and modifiers, categories, brands, images and custom fields. It is a V3 API, which means a consistent JSON envelope, predictable filters and pagination, and batch operations for writes. If you know the conventions once, every catalog endpoint feels familiar.

The real calls need a store and token, so they are shown read-only. The runnable stand-in is a mock catalog service in Node.js that has the same envelope, page and limit pagination, include handling and filters on a small dataset. The behavior of the filters and defaults in the mock is simplified, and we point out where.

Products, variants and options

A product is the thing in the catalog: name, description, price, weight, categories, brand and so on. A product may have variants, which are the concrete sellable combinations (for example a shirt in Blue/Medium), each with its own SKU, price override and inventory. A product's options (such as Color and Size) define the choices a variant is built from. Modifiers are different: they add extras to a product that do not create separate stock items, such as an engraving text field or a gift-wrap checkbox.

The distinction matters because inventory and SKUs belong to variants, while modifiers change what is ordered without being separate items. The general idea is explained in Variants and Options and in The Product Catalog.

Typical endpoints (read-only):

TEXT
GET    /v3/catalog/products
POST   /v3/catalog/products
GET    /v3/catalog/products/{product_id}
PUT    /v3/catalog/products/{product_id}
DELETE /v3/catalog/products/{product_id}
GET    /v3/catalog/products/{product_id}/variants
GET    /v3/catalog/products/{product_id}/options
GET    /v3/catalog/products/{product_id}/modifiers
GET    /v3/catalog/products/{product_id}/custom-fields
GET    /v3/catalog/categories
GET    /v3/catalog/brands

Creating a basic product needs little: a name, a type (physical or digital), a weight for physical products and a price. This request body is read-only:

JSON
{
  "name": "Canvas Tote",
  "type": "physical",
  "sku": "TOTE-01",
  "price": 18.0,
  "weight": 0.4,
  "categories": [23],
  "is_visible": true
}

Variants can be supplied with the product when you create it, or added later at the variants endpoint. Money values here are decimals in the store's currency; inside your own systems, keep amounts in integers as explained in Money as Integers and convert at the edge.

The response envelope

A V3 list response has data (an array) and meta (extra information). meta.pagination has the counts and links:

JSON
{
  "data": [ { "id": 111, "name": "Canvas Tote" } ],
  "meta": {
    "pagination": {
      "total": 42,
      "count": 1,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": { "current": "?page=1&limit=50" }
    }
  }
}

A single resource returns data as an object. Errors come back as JSON with a status code and a message, so check response.ok before parsing.

Pagination

Lists are paged with page (starting at 1) and limit (page size). The platform enforces a maximum limit and uses a default if you omit it, so never assume you received everything: read meta.pagination.total_pages and keep going until you have the last page. A correct loop requests page 1, processes data, and continues while current_page < total_pages. One common bug is to stop when a page returns fewer rows than you hoped, which silently drops data when the platform used a smaller limit than you asked for.

Filters, sorting and includes

List endpoints accept filters as query parameters. Examples include exact fields (sku=TOTE-01, is_visible=true), comparisons with suffixes (price:min, price:max), list matching with :in (id:in=111,112) and text matching with :like (name:like=tote). Sorting uses sort and direction. Which filters exist differs per endpoint, so check the reference.

The include parameter pulls related data into the same response, such as include=variants,images. This saves round trips, at the cost of bigger payloads. A related parameter, include_fields, limits the fields returned, which is often the cheapest optimization for a sync job that only needs a few columns.

sequenceDiagram
    participant Job as "Your script"
    participant API as "Catalog API"
    Job->>API: "GET products?page=1&limit=2&include=variants"
    API-->>Job: "data (2 items) + meta.total_pages = 3"
    Job->>API: "GET products?page=2&limit=2&include=variants"
    API-->>Job: "data (2 items)"
    Job->>API: "GET products?page=3&limit=2&include=variants"
    API-->>Job: "data (1 item), last page"

Walk the pages until current_page equals total_pages.

Batch writes

Creating or updating thousands of products one request at a time is slow and hits rate limits. V3 catalog endpoints accept batch updates: a PUT to the collection with an array of objects that each include an id. Batch sizes are capped (a small number such as 10 products per request for products, and the limit differs by endpoint, so check the reference), which means you chunk your work. Batches also return per-item errors, so look at the response body even when the status is a success. Because retries can happen, write sync code that is safe to repeat; see Idempotency.

A mock catalog service

The stand-in below implements a tiny catalog "API" as a function. It returns the V3-style envelope, supports page, limit, a few filters, sort and include=variants, and walks all pages like a real client would. The data is invented. The real service has many more filters and field rules.

Node.js Mock catalog with pagination and filters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The visible products come back sorted by price in three pages of two, and the loop stops at the last page. "Tote Strap" appears in the name:like search even though it is hidden, because that search did not filter by visibility, a useful reminder that filters combine only if you ask for them.

Chunking batch writes

The second stand-in shows the batch pattern. It splits a list of updates into chunks of the maximum batch size, "sends" each chunk to a fake endpoint that rejects invalid items individually, and collects results. The cap of 10 matches what the products batch endpoint allows, but check the reference for the endpoint you use.

Node.js Chunked batch updates with per-item errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Twenty-three updates become three batches (10, 10 and 3). The fake store holds all 23 products, but the fifth update carries an invalid price, so exactly one item is rejected and 22 are updated. Real code would log such failures, retry only the retryable ones, and never assume a 200 means every item succeeded.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between an option and a modifier?

    Options define the combinations that become variants. Modifiers customize an order line, like engraving text.
  2. 2. How do you know whether you have fetched every product?

    The platform may apply its own limit. Rely on the pagination metadata, not on the row count.
  3. 3. What does the include=variants parameter do?

    include embeds related data and saves extra requests, at the cost of larger responses.
  4. 4. Why check the body of a batch response even on a success status?

    Batch endpoints report errors per item, so partial failure must be handled.

Summary

  • Products hold shared data, variants hold SKUs and stock, options define variants, modifiers add extras.
  • V3 responses use data and meta.pagination; loop with page until current_page reaches total_pages.
  • Use filters (:in, :like, :min, :max), sort, include and include_fields to fetch only what you need.
  • Batch writes are capped; chunk your updates and inspect per-item errors.
  • Write catalog code so that repeating it is safe.

Next: Orders, Customers and the V2/V3 Split