Creating Variant Families

In the product family model, you create variants by creating a product family with classification set to VARIANT, then providing one or more products in that family.

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

Every product in a family must have at least one product code. Codes are not generated automatically. If you do not already have codes to use, generate them first.

1. Generating product codes (Optional)

If you already have codes, you can skip this step.

If you need codes, see Generating Product Codes.

2. Creating a variant family

Send a POST request to /product_families.

For a variant family:

• classification must be VARIANT.
• variant_attribute_ids must contain one to three variant attribute IDs.
• Each product in products must provide variant_attributes values matching the family attributes.
• Each product must have at least one code, either generated or custom.

Request payload:

{
  "name": "T-Shirt",
  "classification": "VARIANT",
  "variant_attribute_ids": [
    "069db350-8d41-11eb-f6a9-869155c00090",
    "2f0ff40b-60ed-48c7-8e32-01d0c9d263ea"
  ],
  "products": [
    {
      "variant_attributes": ["Red", "S"],
      "codes": [{ "type": "CUSTOM", "code": "TSHIRT-RED-S" }]
    },
    {
      "variant_attributes": ["Red", "M"],
      "codes": [{ "type": "CUSTOM", "code": "TSHIRT-RED-M" }]
    }
  ]
}

Response payload:

{
  "data": {
    "product_family_id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
    "product_ids": [
      "0e4066d7-7981-4900-b37c-627fd929ad59",
      "cae9eebf-abfa-4c19-b3cd-c6e4c09c512e"
    ]
  }
}

3. Retrieving the created family

Creation returns IDs only. To retrieve the full representation, call:

GET /product_families/6f32baa8-9a5f-4697-964f-cb2ffa6dff1a

Anything at the top level of data is family-level. Anything inside products is product-level.

4. Adding more variants to an existing family

To add products to an existing variant family, send a POST request to /product_families/{productFamilyID}/products.

The payload is an array of product objects. Each new product must include variant_attributes and at least one product code.

NOTE: You can only add products to a VARIANT family with this endpoint. Adding more products to STANDARD or COMPOSITE families is not currently supported.

Request payload:

[
  {
    "variant_attributes": ["Blue", "S"],
    "codes": [{ "type": "CUSTOM", "code": "TSHIRT-BLUE-S" }]
  },
  {
    "variant_attributes": ["Blue", "M"],
    "codes": [{ "type": "CUSTOM", "code": "TSHIRT-BLUE-M" }]
  }
]

Response payload:

{
  "data": {
    "product_ids": [
      "3d7d399d-1d61-4e18-be08-3f51a586584c",
      "a9e80b33-c580-4dc1-a7aa-62a6cc2141b0"
    ]
  }
}

Validation notes

• Variant families must include variant_attribute_ids.
• The number of variant_attributes values per product must match the family's attributes.
• Duplicate variant attribute combinations in the same family are rejected.
• Unknown fields are rejected.
• Product codes must be unique across the catalog.
• A family can have up to 200 products. If adding products would exceed this limit, the request is rejected.