Updating Standard Families

Once a standard product family and its product exist, you update them with PATCH requests. There are two endpoints, depending on whether the field is family level or belongs to the product:

• PATCH /product_families/{productFamilyID} updates family-level fields (name, description, brand, category, tags, inventory tracking).
• PATCH /products/{productID} updates product-level fields (codes, prices, suppliers, measurements, account codes, tax).

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

If you are unsure which fields are family-level and which are product-level, retrieve the family first. Anything at the top level of the data object is a family-level field, and anything within the products array is a product-level field.

How PATCH works

These endpoints apply a partial update. Only the fields you include in the payload are changed. Any field you leave out is left exactly as it is.

• Omit a field to leave it unchanged.
• Include a field to set it to a new value.
• Send an empty value ("" or null, depending on the field) to clear an optional field back to its default. For example, sending "brand_id": "" removes the brand from the family.
• At least one field must be provided. An empty request body is rejected with at least one field to update must be provided in the request.
• Unknown fields are rejected. Sending a field the endpoint does not recognise returns a bad request error.

Both endpoints respond with the ID of the updated resource:

{
  "data": {
    "id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a"
  }
}

To see the result of your changes, retrieve the family or product again with a GET request.

Updating family-level fields

Send a PATCH request to the /product_families/{productFamilyID} endpoint. The following updates the family description.

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

Request payload:

{
  "description": "Insulated stainless steel travel mug"
}

Response payload:

{
  "data": {
    "id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a"
  }
}

You can update several family-level fields in a single request. Optional references such as brand_id and category_id are set by providing an ID, and cleared by providing an empty string.

Request payload:

{
  "description": "Insulated stainless steel travel mug",
  "brand_id": "",
  "tag_ids": ["3d7d399d-1d61-4e18-be08-3f51a586584c"]
}

In the example above, the description is set, the brand is cleared, and the tags are replaced (see Replacing collections below).

Updating product-level fields

Send a PATCH request to the /products/{productID} endpoint, using the product ID from the family's products array. The following sets the product's price.

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

Request payload:

{
  "prices": {
    "price_excluding_tax": "19.99"
  }
}

Response payload:

{
  "data": {
    "id": "0e4066d7-7981-4900-b37c-627fd929ad59"
  }
}

Replacing collections

Collection fields, such as codes, suppliers, and tag_ids, are replaced wholesale, not merged. The list you provide becomes the complete new set: any existing entries that are not in your payload are removed.

For example, to keep an existing code and add a second one, you must send both in the codes array:

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

Request payload:

{
  "codes": [
    {
      "type": "CUSTOM",
      "code": "1001"
    },
    {
      "type": "UPC",
      "code": "mug-upc"
    }
  ]
}

NOTE: A product must always have at least one code. Sending an empty codes array is rejected with a product must have at least one code. To generate new codes to use here, see Creating Standard Product Families.

Validation notes

A few combinations are rejected to keep the product consistent:

• tax_id and outlet_taxes are mutually exclusive in a single request: either tax ID or outlet taxes can be provided, but not both.
• Only one of price_excluding_tax or price_including_tax may be provided: only one of price excluding tax or price including tax is allowed. Which one is allowed depends on whether your store is tax-inclusive or tax-exclusive.
• When setting measurements, a weight requires a weight unit, and any dimension requires a dimensions unit.

See the Spec for the full list of fields accepted by each endpoint.