Skip to content
Home/
REST API Reference
/
/
Ecommerce Catalog Variant

Ecommerce Catalog Variant

A product variant in an ecommerce catalog upload.

idstring

Unique identifier for this variant within the product.

Example:"var-001"
titlestring

Variant display name shown to shoppers (e.g. "Small / Blue").

Example:"Blue / Large"
pricenumber or null

Price of this specific variant. Fin uses variant prices for precise budget filtering and displays the variant price in recommendation cards.

Example:29.99
compare_at_pricenumber or null

Original price before a discount. When provided, Fin will naturally mention the saving to the shopper (e.g. "down from $129 to $99").

Example:39.99
in_stockboolean

Whether this variant is currently available. Out-of-stock variants are not shown in Fin's recommendation cards and Fin will not suggest them to shoppers.

Example:true
urlstring or null

Direct link to this variant's page. Takes precedence over the product URL in recommendation cards. If omitted, constructed automatically as {product_url}?variant={id}.

Example:"https://example.com/products/t-shirt?variant=var-001"
image_urlstring or null

Image specific to this variant. Takes precedence over the product's featured_image_url. Falls back to featured_image_url, then image_urls. If no valid image can be resolved, this variant's recommendation card will not be shown.

Example:"https://cdn.example.com/images/t-shirt-blue.jpg"
selected_optionsArray of objects

The specific option values that define this variant (e.g. Size=Small, Color=Blue). Fin uses these to match shopper requests like "do you have this in medium?" to the correct variant.

skustring or null

Stock-keeping unit for this specific variant. Fin uses this to resolve shopper requests like "do you have this in size M?" to the exact variant, and can quote it back when a shopper asks for it directly.

Example:"TSHIRT-BLU-L"
{
  "id": "var-001",
  "title": "Blue / Large",
  "price": 29.99,
  "compare_at_price": 39.99,
  "in_stock": true,
  "url": "https://example.com/products/t-shirt?variant=var-001",
  "image_url": "https://cdn.example.com/images/t-shirt-blue.jpg",
  "selected_options": [
    { … }
  ],
  "sku": "TSHIRT-BLU-L"
}