Category Trees

_object

_webhook-events

Brands

Product Custom Fields

Whether or not this modifer is required or not at checkout. Required in a /POST.

The order the modifiers display on the product detail page.

BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

Product Modifiers

The name of the option shown on the storefront.

The unique numerical ID of the product to which the option belongs.

Order in which the option is displayed on the storefront.

The type of option, which determines how it will display on the storefront.

Product Variant Options

Identifies where in a warehouse the variant is located.

The cost price of the variant. Not affected by Price List prices.

Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product's default depth (set in the Product resource's depth field) will be used as the base depth.

A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

Height of the variant, which can be used when calculating shipping costs. If this value is null, the product's default height (set in the Product resource's height field) will be used as the base height.

Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant. The Catalog API returns the inventory for only the default location.

When the variant hits this inventory level, it is considered low stock.

Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.

If true, this variant will not be purchasable on the storefront.

If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s price field) will be used as the retail price.

This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s price field) will be used as the sale price.

The UPC code used in feeds for shopping comparison sites and external channel integrations.

This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.

Width of the variant, which can be used when calculating shipping costs. If this value is null, the product's default width (set in the Product resource's width field) will be used as the base width.

Product Variants

Availability text displayed on the checkout page, under the product title.

You can add a product to an existing brand during a product /PUT or /POST.

You can create the brand during a product PUT or POST request.

The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.

Maximum 200 custom fields per product. Maximum 255 characters per custom field.

The custom URL for the product on the storefront.

Depth of the product, which can be used when calculating shipping costs.

The product description, which can include HTML formatting.

Height of the product, which can be used when calculating shipping costs.

The type of inventory tracking for the product.

Flag used to determine whether the product condition is shown to the customer on the product page.

Flag to determine whether the product should be included in the featured products panel when viewing the store.

Flag used to indicate whether the product has free shipping.

If set to true then on the preorder release date the preorder status will automatically be removed.

Flag indicating whether this product's price should be shown on the product page.

Flag to determine whether the product should be displayed to customers browsing the store.

The layout template file used to render this product category.

Custom meta description for the product page.

Custom meta keywords for the product page.

Flag to determine if product image or open graph image is used.

Flag to determine if product description or open graph description is used.

Flag to determine if product name or open graph name is used.

The maximum quantity an order can contain when purchasing the product.

The minimum quantity an order must contain, to be eligible to purchase this product.

Custom expected-date message to display on the product page.

The price of the product. The price should include or exclude tax, based on the store settings.

If is_price_hidden is true, the value of price_hidden_label is displayed instead of the price.

Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories.

The retail cost of the product. If entered, the retail cost price will be shown on the product page.

The number of times the product has been rated.

The total (cumulative) rating for the product.

If entered, the sale price will be used instead of value in the price field when calculating the product's cost.

A comma-separated list of keywords that can be used to locate the product when searching the store.

A unique user-defined alphanumeric product code/stock keeping unit (SKU).

Priority to give this product when included in product lists on category pages and in search results.

The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)

The product type. One of: physical - a physical stock unit, digital - a digital download.

The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.

The number of times the product has been viewed.

Warranty information displayed on the product page.

Weight of the product, which can be used when calculating shipping costs.

Width of the product, which can be used when calculating shipping costs.

Products

BigCommerce

Returns a list of *Brands*. Optional filter parameters can be passed in.

Get All Brands

Creates a *Brand*.

**Required Fields**
- name

**Read-Only Fields**
- id

**Limits**
- 30,000 brands per store limit

Create a Brand

To delete brand objects, you must include a filter.

**Required Fields**
 - name

Delete Brands

Returns a single *Brand*. Optional filter parameters can be passed in.

Get a Brand

Updates a *Brand*.

**Required Fields**
- None

**Read-Only Fields**
- id

To update a *Brand Image*, send a request with an `image_url`.

Update a Brand

Delete a Brand

Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. 

Get All Brand Metafields

Creates a *Brand Metafield*.

**Required Fields**
- permission_set
- namespace
- key
- value

**Read-Only Fields**
- id

**Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.

Create a Brand Metafield

Returns a *Brand Metafield*. Optional filter parameters can be passed in.

Get a Brand Metafields

Updates a *Brand Metafield*.

**Required Fields**  
* none

**Read-Only Fields**
* id
* These fields can only be modified by the app (API credentials) that created the metafield:
	* namespace
	* key
	* permission_set

**Usage Notes**
* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message.
* The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.

Update a Brand Metafield

Delete a Brand Metafield

Creates a *Brand Image*.

**Required Fields**
- image_file: Form posts are the only accepted upload option.

**Read-Only Fields**
- id

Only one image at a time can be created. To update a *Brand Image*, use the [Update a brand](/docs/rest-catalog/brands#update-a-brand) endpoint and an `image_url`.

Create a Brand Image

Delete a Brand Image

When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead.

Returns a list of *Categories*. Optional filter parameters can be passed in.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Get All Categories

When possible, use the [Category Trees - Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint instead.

Creates a *Category*.

Use this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). 

Use the [Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.

**Required Fields**:
- `parent_id`: 
	- To create a child category, set the `parent_id` to the parent category.
	- To create a top level category, set the `parent_id` to `0`.
- `name`

**Read-Only Fields**:
- `id`

**Limits**:
- 16,000 categories per store limit.
- 1,000 categories per product limit.
- 50 characters category name length.
- 8 levels of category depth limit.
- 65,642 characters category description length limit.

 **Note:**
 The default rate limit for this endpoint is 40 concurrent requests.


Create a Category

When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead.

Deletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation.

**Usage Notes**

- Sending a `DELETE`request without specifying a filter parameter will result in a `422` error. 
- Sending a `DELETE` request for a category that contains products will result in a `422` error. Move products to a new category by sending a `PUT` request to the `/catalog/products/{product_id}` endpoint before deleting a category.

Delete Categories

When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead. You can provide a category identifier using query parameters to retrieve a single category.

Returns a single *Category*. Optional parameters can be passed in.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Get a Category

When possible, use the [Catalog Trees - Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint instead.

Updates a *Category*.

**Required Fields**
* none

**Read-Only Fields**
- id

**Note:** 
The default rate limit for this endpoint is 40 concurrent requests.

Update a Category

When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead. You can provide a category identifier using query parameters to delete a single category.

Deletes a *Category*.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Delete a Category

Returns a list of *Metafields* on a *Category*. Optional filter parameters can be passed in.

Create a Category Metafield

Returns a single *Category Metafield*. Optional parameters can be passed in.

Update a Category Metafield

Delete a Category Metafield

Create a *Category Image*.

 **Required Fields**
- image_file: Form posts are the only accepted upload option.

Only one image at a time can be created.
Limit image size to 1MB.
To update a *Category Image*, use the [Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint and an `image_url`.

Create a Category Image

Delete a Category Image

Returns a list of products and their sort order for a specific category.

**Usage Notes**
* Data pairs are displayed in ascending order based on products' `sort_order` values.
* `null` values are allowed for products without specified `sort_order` values.
* Products with `sort_order` value of `null` will be displayed after products with valid numerical values.
* The priorities for determining product sort order on a storefront are the following:
  - Priority 1: Manually specified sort order on Category Level (API).
  - Priority 2: Manually specified sort order on Product (Global) Level (UI/API).
  - Priority 3: Default sorting by Product ID (newly added products go first) (UI/API).

Get Product Sort Order

Updates sort order of products within a specific category.

Update Product Sort Order

Returns a list of all *Product Modifiers*. Optional parameters can be passed in.

Get All Product Modifiers

Creates a *Product Modifier*.

**Required Fields**
* `required`
* `display_name`
* `type`

**Read-Only Fields**
* `id`

**Notes**
It takes two separate requests to create a new checkbox modifier with option values. Perform a request to create a modifier, then perform a second request to update option values.

Create a Product Modifier

Returns a single *Product Modifier*. Optional parameters can be passed in.

Get a Product Modifier

Update a Product Modifier

Delete a Product Modifier

Returns a list of all product *Modifier Values*. Optional parameters can be passed in.

Get All Product Modifier Values

Creates a *Modifier Value*.

**Required Fields**
* label
* sort_order

**Read-Only Fields**
* id

Create Product Modifier Value

Returns a single *Modifier Value*. Optional parameters can be passed in.

Get a Product Modifier Value

Updates a *Modifier Value*.

**Required Fields**
* none

**Read-Only Fields**
* id

Update a Product Modifier Value

Delete Product Modifier Value

Creates a *Modifier Image*.

The image will show on the storefront when the value is selected.

 **Required Fields**
- image_file: Form posts are the only accepted upload option.

Create Product Modifier Image

Returns a list of product *Variant Options*. Optional parameters can be passed in. 

Get All Product Variant Options

Creates a *Variant Option*.

**Required Fields**
* display_name
* type
* option_values

**Read-Only Fields**
* id

**Limits**
* 255 characters option name length.

**Notes**

* Only one variant option at a time can be created; individual variant options will contain an array of multiple values.
* There are several examples listed below that create options, but the SKUs are not updated and they are not a variant on the product. Variant SKUs must be created with a separate request.
* Variant options will show on the storefront as an option that can be selected by the customer. A request like this could be used to add new choices to a variant that has already been created.
* If more than one variant needs to be created, use the [Create a Product](/docs/rest-catalog/products#create-a-product) endpoint.

Create a Product Variant Option

Returns a single *Variant Option*. Optional parameters can be passed in.

Get a Product Variant Option

Updates a *Variant Option*.

**Read-Only Fields**
* id

Update a Product Variant Option

Delete a Product Variant Option

Returns a list of all *Variant Option Values*. Optional parameters can be passed in.

Get All Product Variant Option Values

Creates a *Variant Option Value*.

**Required Fields**
* label
* sort_order

**Read-Only Fields**
* id

**Limits**
* 250 option values per option limit.

Create a Product Variant Option Value

Returns a single *Variant Option Value*. Optional parameters can be passed in.

Get a Product Variant Option Value

Updates a *Variant Option Value*.

**Read-Only Fields**
* id

Update a Product Variant Option Value

Delete a Product Variant Option Value

Returns a list of product *Variants*. Optional parameters can be passed in.

Get All Product Variants

Creates a *Product Variant*.

**Required Fields**
* sku
* option_values

**Read-Only Fields**
* id

**Limits**
* 600 SKUs per product limit.
* 255 characters SKU length limit.

Variants need to be created one at a time using this endpoint. To use a variant array and create products and variants in the same call use the [Create Products](/docs/rest-catalog/products#create-a-product) during the initial product creation.

Create a Product Variant

Returns a single product *Variant*. Optional parameters can be passed in.

Get a Product Variant

Update a Product Variant

Delete a Product Variant

Returns a list of product variant *Metafields*. Optional parameters can be passed in.

Get All Product Variant Metafields

Creates a product variant *Metafield*.

**Required Fields:**
* permission_set
* namespace
* key
* value

**Read-Only Fields**
* id

**Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.

Create a Product Variant Metafield

Returns a single product variant *Metafield*. Optional parameters can be passed in.

Get a Product Variant Metafields

Updates a product variant *Metafield*.

**Required Fields:**
* none

**Read-Only Fields**
* id
* These fields can only be modified by the app (API credentials) that created the metafield:
	* namespace
	* key
	* permission_set

**Usage Notes**
* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. 

Update Product Variant Metafields

Delete a Product Variant Metafield

Creates a *Variant Image*.

Only one image can be explicitly associated with a Variant. If the Variant already has an associated image, overwrites the existing Variant Image.

The image displays on the storefront when the Variant is selected.

 **Required Fields**
- image_file: Form posts. Files larger than 1 MB are not accepted
- image_url: Any publicly available URL

Create a Product Variant Image

Returns a list of all variants in your catalog. Optional parameters can be passed in.

Get All Variants

Updates a batch of `variant` objects. Currently the limit is 50 variants however this is subject to change.

**Required Fields**

To update an existing variant:
* id (variant id)

To create a new variant:
* product_id
* sku
* option_values
  - id (option_value ID - Example: 146)
  - option_id (Option ID - Example: 151)

Update Variants (Batch)

Returns a list of **Products**. Optional filter parameters can be passed in.

Get All Products

Updates products in batches. Batches are limited to 10 products.

**Required Fields**
* `id` - product `id` is required for batch updates to products.

**Read-Only Fields**
- `id`
- `date_created`
- `date_modified`
- `calculated_price`
- `base_variant_id`

Update Products (Batch)

Creates a *Product*. Only one product can be created at a time; however, you can create multiple product variants using the `variants` array.

**Required Fields:**
- `name`
- `type`
- `weight`
- `price`

**Read-Only Fields**
- `id`
- `date_created`
- `date_modified`
- `calculated_price`
- `base_variant_id`

**Limits**
- 250 characters product name length.
- A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB.

**Usage Notes**
* You can create multiple product variants using the `variants` array.
* This endpoint accepts a `video` array. To create a product video that accepts a `video` object, see [Create a Product Video](/docs/rest-catalog/products/videos#create-a-product-video) for information.

Create a Product

To delete *Product* objects, you must include a filter. This prevents inadvertently deleting all *Product* objects in a store.

> #### Note
> The maximum number of products you can delete at one time is 250.

**Example**:
To delete products with the id's of 1,2 and 3, use `DELETE /v3/catalog/products?id:in=1,2,3`.

Delete Products

Returns a single *Product*. Optional parameters can be passed in.

Get a Product

Updates a *Product*.

**Limits**
- A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB.

**Read-Only Fields**
- id
- date_created
- date_modified
- calculated_price
- base_variant_id


Update a Product

Delete a Product

Returns a list of *Product Images*. Optional parameters can be passed in.

Field Name	API Key	Type
Id	id	integer
Name	name	string
Channels	channels	array of integers

BigCommerce API Integration Profile

How to work with Category Trees in BigCommerce API

Operations on Category Trees Collection

Build every single integration your customers need with AI