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

Send a POST request to /products/generate_product_codes.

Each entry in codes requests a count of generated codes, with an optional prefix.

Request payload:

{
  "codes": [{ "count": 2 }, { "prefix": "shirt", "count": 2 }]
}

Response payload:

{
  "data": [{ "codes": ["1001", "1002"] }, { "codes": ["shirt", "shirt1"] }]
}

NOTE: A single request may generate up to 200 codes in total.

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.