Updating Variant Families and Products

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

PATCH /product_families/{familyID} for family-level fields.
PATCH /products/{productID} for product-level fields.

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

How PATCH works

Both endpoints are partial updates:

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": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a"
  }
}

Updating family-level fields

Send a PATCH request to /product_families/{familyID}.

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

Request payload:

{
  "description": "Classic fit crew neck t-shirt",
  "tag_ids": ["3d7d399d-1d61-4e18-be08-3f51a586584c"]
}

This updates family-level fields and applies across all products in the family.

Updating product-level fields

Send a PATCH request to /products/{productID}.

PATCH /products/0e4066d7-7981-4900-b37c-627fd929ad59

Request payload:

{
  "prices": {
    "price_excluding_tax": 39.99
  },
  "variant_attributes": ["Red", "M"]
}

This updates only the product identified by productID.

Replacing collections

Collection fields are replaced wholesale, not merged.

For example, when updating codes, provide the full list you want to keep:

PATCH /products/0e4066d7-7981-4900-b37c-627fd929ad59

Request payload:

{
  "codes": [
    {
      "type": "CUSTOM",
      "code": "TSHIRT-RED-M"
    },
    {
      "type": "UPC",
      "code": "TSHIRT-RED-M-UPC"
    }
  ]
}

If you omit an existing code from the list, it is removed.

Adding a new variant attribute to an existing family

If a family currently has one variant attribute (for example, Size) and you want to add a second one (for example, Colour), update the family and then update every product.

Recommended order:

Create the new variant attribute and keep its ID.
Update the family with PATCH /product_families/{familyID} so variant_attribute_ids contains the complete new ordered set.
Update each product in the family with PATCH /products/{productID} so variant_attributes has values for the complete new set.
Ensure every product ends with a full and unique attribute combination.

Example family update:

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

Request payload:

{
  "variant_attribute_ids": [
    "2f0ff40b-60ed-48c7-8e32-01d0c9d263ea",
    "069db350-8d41-11eb-f6a9-869155c00090"
  ]
}

Then update each product with values for both attributes:

PATCH /products/0e4066d7-7981-4900-b37c-627fd929ad59

Request payload:

{
  "variant_attributes": ["M", "Green"]
}

PATCH /products/cae9eebf-abfa-4c19-b3cd-c6e4c09c512e

Request payload:

{
  "variant_attributes": ["S", "Blue"]
}

Until all products have been updated, you may get validation errors if a product has an incomplete or non-unique combination.

Validation notes

variant_attributes are only valid on products in a variant family.
A variant product must provide a value for each family variant attribute.
Variant attribute combinations must remain unique in the family.