The Product object

Every field of the Product object — types, required flags and validation rules.

Product

Field	Type	Description
`id`	string	e.g. `prod_66a1f09b2`
`object`	string	always `product`
`title`	string · nullable	e.g. `Vintage denim jacket`
`description`	string · nullable
`brand`	string · nullable
`category`	string · nullable	Seller's own product category / collection label (free text; channel categories live on the listing).
`short_description`	string · nullable
`vat_rate`	number · nullable	VAT percentage applied to this product
`mpn`	string · nullable	Manufacturer part number.
`weight`	object	Product-level shipping weight.
`weight.value`	string · nullable	Decimal number as a string.
`weight.unit`	string · nullable	one of: `oz`, `lb`, `g`, `kg`, `null`
`dimensions`	object	Package dimensions.
`dimensions.length`	string · nullable
`dimensions.width`	string · nullable
`dimensions.height`	string · nullable
`dimensions.unit`	string · nullable	one of: `in`, `ft`, `yd`, `mm`, `cm`, `m`, `null`
`tags`	array of string
`currency`	string	ISO-4217; echo of the store base currency.
`status`	ProductStatus	New values may be added; tolerate unknowns. — one of: `ready`, `listed`, `archived`, `sold_out`, `error`, `ongoing`
`sync_status`	string	Rollup of the listings' statuses. — one of: `ok`, `pending`, `error`
`images`	array of Image
`variants`	array of Variant
`listings`	array of ListingSummary	Read-only summary; the canonical resource is `GET /listings?product_id=`.
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601

Field	Type	Description
`id`	string	e.g. `var_66a1f1`
`object`	string	always `variant`
`sku`	string · nullable	e.g. `VDJ-M-001`
`title`	string · nullable
`price`	string (money)	Decimal string, 2 decimals. e.g. `19.90`
`msrp`	object	Compare-at / list price, shown struck-through on channels that support it.
`quantity`	integer
`barcode`	string · nullable
`grams`	number · nullable	Variant weight in grams (used for shipping on supported channels).
`asin`	string · nullable	Amazon ASIN
`images`	array of object	Variant-specific images, referencing the product's images.
`images[].image_id`	string	e.g. `img_66a1f2`
`images[].url`	string · nullable	uri
`images[].position`	integer
`options`	object	Option name → value (e.g. `{"Color": "Red", "Size": "M"}`).

Field	Type	Description
`id`	string	e.g. `img_ph1x8`
`object`	string	always `image`
`url`	string	uri
`alt`	string · nullable
`position`	integer	Zero-based; equals array index.

What you send when creating or updating. Anything not listed is rejected.

Field	Type	Required	Description
`title`	string	required	max 255 chars
`description`	string	optional
`brand`	string	optional
`tags`	array of string	optional
`images`	array of ImageInput	optional	max 20 items
`variants`	array of VariantInput	optional	Omit for a single-variant product (top-level `price`/`quantity`/`sku` instead). When variants carry `options`, they must cover EVERY combination of the option values (dense matrix) — channels generate the full matrix, so sparse sets are rejected with `422`. Variant titles are built automatically from the option values. — max 100 items
`price`	string (money)	optional	Decimal string, 2 decimals. e.g. `19.90`
`msrp`	string (money)	optional	Decimal string, 2 decimals. e.g. `19.90`
`quantity`	integer	optional	min 0
`sku`	string	optional
`grams`	number	optional	min 0
`category`	string	optional	max 255 chars
`short_description`	string	optional
`vat_rate`	number	optional	min 0
`mpn`	string	optional	max 70 chars
`weight`	object	optional
`weight.value`	string	optional	Decimal number as a string
`weight.unit`	string	optional	one of: `oz`, `lb`, `g`, `kg`
`dimensions`	object	optional
`dimensions.length`	string	optional
`dimensions.width`	string	optional
`dimensions.height`	string	optional
`dimensions.unit`	string	optional	one of: `in`, `ft`, `yd`, `mm`, `cm`, `m`

Field	Type	Required	Description
`title`	string	optional	max 255 chars
`description`	string	optional
`brand`	string	optional
`category`	string	optional	max 255 chars
`short_description`	string	optional
`vat_rate`	number	optional	min 0
`mpn`	string	optional	max 70 chars
`weight`	object	optional
`weight.value`	string	optional	Decimal number as a string
`weight.unit`	string	optional	one of: `oz`, `lb`, `g`, `kg`
`dimensions`	object	optional
`dimensions.length`	string	optional
`dimensions.width`	string	optional
`dimensions.height`	string	optional
`dimensions.unit`	string	optional	one of: `in`, `ft`, `yd`, `mm`, `cm`, `m`
`tags`	array of string	optional
`images`	array of ImageInput	optional	Desired state, id-keyed diff — see endpoint description. — max 20 items
`expected_updated_at`	string	optional	Optimistic-concurrency precondition; `412` on mismatch. — ISO 8601

Field	Type	Required	Description
`sku`	string	optional
`title`	string	optional
`price`	string (money)	optional	Decimal string, 2 decimals. e.g. `19.90`
`msrp`	string (money)	optional	Decimal string, 2 decimals. e.g. `19.90`
`quantity`	integer	optional	min 0
`barcode`	string	optional
`grams`	number	optional	Variant weight in grams. — min 0
`asin`	string	optional	max 20 chars
`options`	object	optional

One of url or base64 for new images; pass id alone to keep an existing image.

Field	Type	Required	Description
`id`	string	optional	Existing image id (keeps it untouched).
`url`	string	optional	Publicly fetchable image URL. — uri
`base64`	string	optional	Base64-encoded image (max 10 MB).
`alt`	string	optional

Last updated on July 30, 2026

Need help?

The API is in private beta — email us and a human replies, usually within one business day.