Creating Standard Product Families

A standard product family is the simplest product family. Unlike variants, it contains a single product and requires no variant attributes or composite components. When the classification is omitted, the family is created as STANDARD.

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

The payloads below are intentionally minimal (just name and codes). Any additional details, such as prices, suppliers, tax, brand, category, or tags, can be added later. See the section at the end for how to add them.

Every product in a family must have at least one product code. Unlike previous versions, codes are not generated automatically if they are omitted, and a request to create a product without a code is rejected. If you do not already have a code to use, generate one first with the /generate_product_codes endpoint described below.

1. Generating a product code (Optional)

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

To generate a code, send a POST request to the /products/generate_product_codes endpoint. Each entry in codes requests a count of codes, with an optional prefix. When no prefix is supplied, numeric codes are generated from your configured SKU sequence.

Request payload:

{
  "codes": [
    {
      "count": 1
    }
  ]
}

The API responds with the generated codes, grouped per requested entry.

Response payload:

{
  "data": [
    {
      "codes": ["1001"]
    }
  ]
}

NOTE: To generate codes that share a common prefix, include a prefix (for example { "prefix": "mug", "count": 2 }), which returns codes such as mug and mug1. A single request may generate up to 200 codes in total.

2. Creating a standard product family

To create a standard product family, send a POST request to the /product_families endpoint. The name is required, and each product must include at least one code under the products array. Use a code you generated in the previous step. Because classification is left out, the family is created as STANDARD.

NOTE: The type field accepts CUSTOM, EAN, ISBN, ITF, JAN, or UPC.

Request payload:

{
  "name": "Coffee Mug",
  "products": [
    {
      "codes": [
        {
          "type": "CUSTOM",
          "code": "1001"
        }
      ]
    }
  ]
}

The API responds with the ID of the created family and the IDs of the products within it. A family always contains at least one product, so product_ids will contain a single ID for a standard family.

Response payload:

{
  "data": {
    "product_family_id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
    "product_ids": ["0e4066d7-7981-4900-b37c-627fd929ad59"]
  }
}

3. Retrieving the product family

These APIs only return the IDs of the created resources. To get the full representation, make a GET request to the /product_families/{productFamilyID} endpoint using the product_family_id from the previous response.

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

Note that we provided a minimal payload, so the classification is STANDARD and everything we did not supply has been defaulted (either null or an empty value). The product code we provided in the previous step is returned under the product's codes array. Anything you see in this response, can also be provided in the create request, except for some generated fields, like ids, sequences and versions. See the Spec for details.

Response payload:

{
  "data": {
    "id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
    "brand_id": null,
    "category_id": null,
    "name": "Coffee Mug",
    "description": null,
    "classification": "STANDARD",
    "family_count": 1,
    "track_inventory": true,
    "variant_attribute_ids": null,
    "tag_ids": null,
    "images": null,
    "composite_bom": null,
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-01T12:00:00Z",
    "deleted_at": null,
    "products": [
      {
        "id": "0e4066d7-7981-4900-b37c-627fd929ad59",
        "family_id": "6f32baa8-9a5f-4697-964f-cb2ffa6dff1a",
        "variant_parent_id": null,
        "variant_name": "Coffee Mug",
        "sku": "1001",
        "active": { "in_store": true, "ecwid": true },
        "source": { "source": "USER", "id": null, "variant_id": null },
        "account_code": { "sale": null, "purchase": null },
        "variant_attributes": null,
        "prices": {
          "price_excluding_tax": "0",
          "price_including_tax": null,
          "tax": null,
          "loyalty_amount": null
        },
        "measurements": {
          "weight": null,
          "weight_unit": null,
          "dimensions_length": null,
          "dimensions_width": null,
          "dimensions_height": null,
          "dimensions_unit": null
        },
        "sequence": 1,
        "version": 27561014304,
        "images": null,
        "suppliers": null,
        "packaging": null,
        "codes": [
          {
            "type": "CUSTOM",
            "code": "1001",
            "created_at": "2026-10-01T12:00:00Z",
            "updated_at": "2026-10-01T12:00:00Z"
          }
        ],
        "outlet_taxes": [],
        "created_at": "2026-10-01T12:00:00Z",
        "updated_at": "2026-10-01T12:00:00Z",
        "deleted_at": null
      }
    ]
  }
}

NOTE: You can also retrieve the individual product directly with a GET request to /products/{productID}.

Anything at the top level of the data object is a family-level field. Anything within the products array is a product-level field.

Adding more detail later

Once the product family and its products have been created, you can update the products and the family using the following endpoints.

Update product-level details with a PATCH request to /products/{productID}.
Update family-level details with a PATCH request to /product_families/{productFamilyID}.