HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference

Create Catalog Variant

Create a new variant for a related catalog item.

Rate limits:
Burst: 75/s
Steady: 700/m

Scopes:
catalogs:write

Body Params
object
required
string
required
object
required
string
required

The ID of the catalog item variant in an external system.

string
Defaults to $default

The type of catalog. Currently only "$default" is supported.

string
Defaults to $custom

The integration type. Currently only "$custom" is supported.

string
required

The title of the catalog item variant.

string
required

A description of the catalog item variant.

string
required

The SKU of the catalog item variant.

integer
Defaults to 0

This field controls the visibility of this catalog item variant in product feeds/blocks. This field supports the following values:
1: a product will not appear in dynamic product recommendation feeds and blocks if it is out of stock.
0 or 2: a product can appear in dynamic product recommendation feeds and blocks regardless of inventory quantity.

number
required

The quantity of the catalog item variant currently in stock.

number
required

This field can be used to set the price on the catalog item variant, which is what gets displayed for the item variant when included in emails. For most price-update use cases, you will also want to update the price on any parent items using the Update Catalog Item Endpoint.

string
required

URL pointing to the location of the catalog item variant on your website.

string

URL pointing to the location of a full image of the catalog item variant.

string

URL pointing to the location of an image thumbnail of the catalog item variant.

array of strings

List of URLs pointing to the locations of images of the catalog item variant.

images
object

Flat JSON blob to provide custom metadata about the catalog item variant. May not exceed 100kb.

string
boolean
Defaults to true

Boolean value indicating whether the catalog item variant is published.

object
required
object
required
object
string
required
string
required

The original catalog item ID for which this is a variant.

Headers
string
required
Defaults to 2025-01-15

API endpoint revision (format: YYYY-MM-DD[.suffix])

Responses

Language
Credentials