Products and variants
Tell Metr which item is being sized and which sizes are available to buy.
Product contract
curl --fail-with-body -X POST "$METR_API_URL/v1/stores/$STORE_ID/products" \
-H "Authorization: Bearer $METR_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"external_id": "linen-shirt",
"title": "Linen camp-collar shirt",
"product_type": "shirt",
"gender": "unisex",
"garment_fit": "regular",
"stretch": "none",
"size_chart_id": "cht_example"
}'| Field | Meaning |
|---|---|
| external_id | Your catalog identifier; unique within a store, up to 128 characters. |
| product_type | A supported type from GET /v1/product-types. |
| gender | women, men or unisex. Adult product metadata, not a customer inference. |
| garment_fit | fitted, regular, relaxed or oversized. |
| stretch | none, moderate or high. Not an invented stretch percentage. |
| size_chart_id | An approved, category-compatible chart from the same store. |
Supported categories
| Category | Examples | Required chart measurements |
|---|---|---|
| tops | t_shirt, shirt, kurta, sweater, jacket | chest |
| bottoms | trousers, jeans, shorts, skirt | waist and hips |
| one_piece | dress, jumpsuit | chest, waist and hips |
| footwear | shoes | foot_length on a body chart |
accessory is recognized but does not support recommendations. Children’s products, bras and separately sized multi-piece sets need a different model and are not supported by V1.
Available variants
curl --fail-with-body -X POST "$METR_API_URL/v1/stores/$STORE_ID/products/$PRODUCT_ID/variants" \
-H "Authorization: Bearer $METR_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"external_id": "linen-shirt-M",
"size": "M",
"color": "black",
"available": true
}'A variant ID belongs to one product, merchant and store. Size labels match chart rows exactly, including case. Multiple colors can share one size. Send color when starting a session to recommend only variants of that color.
Keep inventory current
Use PUT on the product or variant resource to replace its documented input fields. Set available=false as soon as a variant is unavailable. Variant size and color are immutable; create a new variant if either changes. Chart-backed recommendations never invent a size that is absent from current available inventory. An already-returned recommendation is historical, so recheck stock before adding to cart.
List endpoints return data and optional next_cursor. Use ?limit=50&cursor=LAST_CURSOR. The maximum page size is 100. Creation is not generally idempotent: use your external_id and the list/get/PUT flow to reconcile interrupted catalog syncs.