Creating Composite Families

In the product family model, a composite is created as a product family with:

classification set to COMPOSITE
exactly one product in products
a non-empty composite_components list of component products

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

Component products must already exist. A component cannot be a composite product.

1. Generate product codes (Optional)

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

If you need codes, see Generating Product Codes.

2. Create a composite family

Send a POST request to /product_families.

Assume we want to create a gift basket that includes two existing products. A Mug, and Coffee Beans. We have the following product IDs:

7cea940d-28fb-4088-822b-d20b098095fc = Coffee Beans
42ca6417-e0eb-4190-a5a7-e6047151396b = Ceramic Mug

The quantity values in composite_components mean this gift basket includes 2 bags of coffee beans and 1 mug.

Example request:

{
  "name": "Gift Basket",
  "classification": "COMPOSITE",
  "composite_components": [
    {
      "product_id": "7cea940d-28fb-4088-822b-d20b098095fc",
      "quantity": 2
    },
    {
      "product_id": "42ca6417-e0eb-4190-a5a7-e6047151396b",
      "quantity": 1
    }
  ],
  "products": [
    {
      "codes": [{ "type": "CUSTOM", "code": "GIFT-BASKET" }]
    }
  ]
}

Example response:

{
  "data": {
    "product_family_id": "765d2013-216d-45d9-aa33-613eabd5f4f0",
    "product_ids": ["58f04f4e-2865-4f50-a503-2d726d0afafe"]
  }
}

3. Retrieve the created family

Creation returns IDs only.

Retrieve the full representation with either endpoint:

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

Example response:

{
  "data": {
    "id": "765d2013-216d-45d9-aa33-613eabd5f4f0",
    "name": "Gift Basket",
    "classification": "COMPOSITE",
    "family_count": 1,
    "variant_attribute_ids": null,
    "tag_ids": null,
    "images": null,
    "composite_components": [
      {
        "product_id": "7cea940d-28fb-4088-822b-d20b098095fc",
        "quantity": "2"
      },
      {
        "product_id": "42ca6417-e0eb-4190-a5a7-e6047151396b",
        "quantity": "1"
      }
    ],
    "products": [
      {
        "id": "58f04f4e-2865-4f50-a503-2d726d0afafe",
        "family_id": "765d2013-216d-45d9-aa33-613eabd5f4f0",
        "codes": [
          {
            "type": "CUSTOM",
            "code": "GIFT-BASKET"
          }
        ]
      }
    ]
  }
}

If you also need the full details of each component product, add includes[]=composite_components.

Example request:

GET /product_families/765d2013-216d-45d9-aa33-613eabd5f4f0?includes[]=composite_components

Example response (abbreviated):

{
  "data": {
    "id": "765d2013-216d-45d9-aa33-613eabd5f4f0",
    "classification": "COMPOSITE",
    "composite_components": [
      {
        "product_id": "7cea940d-28fb-4088-822b-d20b098095fc",
        "quantity": "2"
      },
      {
        "product_id": "42ca6417-e0eb-4190-a5a7-e6047151396b",
        "quantity": "1"
      }
    ]
  },
  "includes": {
    "composite_components": [
      {
        "id": "7cea940d-28fb-4088-822b-d20b098095fc",
        "family_id": "d3643fd0-b525-4490-81f1-b941c8bb0b8f",
        "variant_name": "Coffee Beans",
        "codes": [{ "type": "CUSTOM", "code": "COFFEE-BEANS" }]
      },
      {
        "id": "42ca6417-e0eb-4190-a5a7-e6047151396b",
        "family_id": "f9f5ea86-7835-4d6a-8748-00a946f5525d",
        "variant_name": "Ceramic Mug",
        "codes": [{ "type": "CUSTOM", "code": "CERAMIC-MUG" }]
      }
    ]
  }
}

Validation notes

classification must be COMPOSITE for families using composite_components.
Composite families require at least one component with a positive quantity.
Duplicate component product_id values are rejected.
Composite products cannot be nested.
A component product cannot be deleted while it is still referenced by any composite.