Variants

A variant family is a family with multiple products that differ by one or more attributes (for example, colour and size). If you are new to the family model, read Products and Product Families first.

This means variant data is now split across two levels:

Family-level fields (shared by all variants), such as name, description, brand_id, category_id, tag_ids, track_inventory, and variant_attribute_ids.
Product-level fields (specific to each variant), such as codes, prices, suppliers, measurements, outlet_taxes, and variant_attributes.

This guide uses the {version} product and product family endpoints. The base URL for all requests is https://DOMAIN_PREFIX.retail.lightspeed.app/api/{version}/.

How to recognize a variant family

A family is a variant family when:

classification is VARIANT.
variant_attribute_ids contains one to three attribute IDs for the family (for example, colour and size).

Each product in that family then provides its own variant_attributes values in the same order as the family's variant_attribute_ids.

For example, if variant_attribute_ids represent Colour and Size, then a product with variant_attributes: ["Red", "M"] is the Red / M variant.

Retrieving a variant family

You can retrieve the full family representation with either endpoint:

GET /product_families/{productFamilyID}
GET /products/{productID}/family

Both return the full family and its products array.

Response payload:

{
  "data": {
    "id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
    "brand_id": null,
    "category_id": null,
    "name": "T-Shirt",
    "description": null,
    "classification": "VARIANT",
    "family_count": 2,
    "track_inventory": true,
    "variant_attribute_ids": [
      "069db350-8d41-11eb-f6a9-869155c00090",
      "2f0ff40b-60ed-48c7-8e32-01d0c9d263ea"
    ],
    "tag_ids": null,
    "images": null,
    "composite_components": null,
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-01T12:00:00Z",
    "deleted_at": null,
    "products": [
      {
        "id": "0e4066d7-7981-4900-b37c-627fd929ad59",
        "family_id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
        "variant_name": "T-Shirt / Red / M",
        "active": { "in_store": true, "ecwid": true },
        "source": { "source": "USER", "id": null, "variant_id": null },
        "account_code": { "sale": null, "purchase": null },
        "variant_attributes": ["Red", "M"],
        "prices": {
          "price_excluding_tax": "39.99",
          "price_including_tax": null,
          "tax": null,
          "loyalty_amount": null
        },
        "measurements": {
          "weight": null,
          "weight_unit": null,
          "dimensions_length": null,
          "dimensions_width": null,
          "dimensions_height": null,
          "dimensions_unit": null
        },
        "sequence": 1,
        "version": 27561014304,
        "images": null,
        "suppliers": null,
        "packaging": null,
        "codes": [
          {
            "type": "CUSTOM",
            "code": "TSHIRT-RED-M",
            "created_at": "2026-10-01T12:00:00Z",
            "updated_at": "2026-10-01T12:00:00Z"
          }
        ],
        "outlet_taxes": [],
        "created_at": "2026-10-01T12:00:00Z",
        "updated_at": "2026-10-01T12:00:00Z",
        "deleted_at": null
      },
      {
        "id": "cae9eebf-abfa-4c19-b3cd-c6e4c09c512e",
        "family_id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
        "variant_name": "T-Shirt / Blue / M",
        "active": { "in_store": true, "ecwid": true },
        "source": { "source": "USER", "id": null, "variant_id": null },
        "account_code": { "sale": null, "purchase": null },
        "variant_attributes": ["Blue", "M"],
        "prices": {
          "price_excluding_tax": "39.99",
          "price_including_tax": null,
          "tax": null,
          "loyalty_amount": null
        },
        "measurements": {
          "weight": null,
          "weight_unit": null,
          "dimensions_length": null,
          "dimensions_width": null,
          "dimensions_height": null,
          "dimensions_unit": null
        },
        "sequence": 2,
        "version": 27561014305,
        "images": null,
        "suppliers": null,
        "packaging": null,
        "codes": [
          {
            "type": "CUSTOM",
            "code": "TSHIRT-BLUE-M",
            "created_at": "2026-10-01T12:00:00Z",
            "updated_at": "2026-10-01T12:00:00Z"
          }
        ],
        "outlet_taxes": [],
        "created_at": "2026-10-01T12:00:00Z",
        "updated_at": "2026-10-01T12:00:00Z",
        "deleted_at": null
      }
    ]
  }
}

Creating and updating variants

For creation flows, see Creating Variant Families.
For updates, see Updating Variant Families and Products.

Gotchas

Family attributes vs product values

variant_attribute_ids define the family's attribute dimensions. Each product's variant_attributes supplies the concrete values and must align with those dimensions.