Updating Composite Families and Products

In the product family model, updates are split across two endpoints:

• PATCH /product_families/{productFamilyID} for family-level fields, including composite_components.
• PATCH /products/{productID} for product-level fields, such as codes and prices.

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

How PATCH works

• Omit a field to leave it unchanged.
• Include a field to set or replace it.
• At least one field must be present in the payload, for it to be a valid update.
• Unknown fields are rejected with a bad request error.

Both endpoints return the updated resource ID:

{
  "data": {
    "id": "765d2013-216d-45d9-aa33-613eabd5f4f0"
  }
}

Updating a composite BOM

To replace the components of a composite family, send PATCH to /product_families/{familyID} with composite_components.

PATCH /product_families/765d2013-216d-45d9-aa33-613eabd5f4f0

{
  "composite_components": [
    {
      "product_id": "028f8492-636f-4c95-b11c-650a43cad10c",
      "quantity": 3
    },
    {
      "product_id": "162a2294-cbba-46bf-8069-b86d0381193e",
      "quantity": 2
    }
  ]
}

composite_components is treated as a full replacement list:

• Existing components omitted from the request are removed.
• Existing components included with a new quantity are updated.
• New component product IDs are added.

The list cannot be empty. Sending "composite_components": [] does not clear all components.

Updating product-level fields in a composite family

Use PATCH /products/{productID} to update only the composite product itself.

PATCH /products/58f04f4e-2865-4f50-a503-2d726d0afafe

{
  "codes": [
    {
      "type": "CUSTOM",
      "code": "GIFT-BASKET-V2"
    }
  ],
  "prices": {
    "price_excluding_tax": 29.99
  }
}

Collection fields such as codes are replaced wholesale.

Validation notes

• composite_components is only valid on families with classification COMPOSITE.
• Each component must reference an existing, non-deleted product.
• Component quantities must be positive.
• Duplicate product_id values in one composite_components request are rejected.
• Component products cannot be composite products.
• A product used as a component cannot be deleted until removed from all composite BOMs.