Variants

Product structure and how to recognize variants

In order to understand how variants work, it's important to understand the way they are represented in the API and the Lightspeed Retail (X-Series) database. The core of the concept is that there is always a variant parent and at least one variant child (the parent and child can be the same product). There is a limit of 200 variants per family.

Parent - Child relationship

Products have a few attributes which define how they are involved in a variant product.

Name

The most important field is the name. The name is the field that groups a variant family. The only way products can have the same name is if they are in the same variant family.

variant_parent_id and has_variants

Once a variant product is created, variant_parent_id and has_variants allow the API consumer to recognize what part a particular product is playing in the parent-child relationship.

It's important to remember that those are read-only attributes and they cannot be used to modify to remove a product from a variant product or reassign it to another product. A variant child will have the variant_parent_id set, and a variant parent will not.

There are 3 possible combinations in which those attributes can exist:

• Standard, simple product - no variants involved

• The main product - variant parent

• The variant product - variant child

Some older APIs, such as in the 0.9 version, only accept the variant parent id when operating on the entire family, and the child IDs when dealing with each child. This has been simplified in the 2.1 product API where any ID in the family is accepted, and different sections of the payload describing family fields vs individual fields. This limitation is driven by the has_variants value, which is only present on the parent product. The parent is now retrieve when using the 2.1 API, so it no longer matters which ID in the family you use.

Variant options - variant's unique characteristics

Apart from the "structural" attributes discussed above, there are also some which define unique properties of each variant (parent or child) - so-called variant options. In total, Lightspeed Retail (X-Series) allows the user to define 3 different options. The options are usually used to describe properties like color, size, fabric, etc.
A simple example of a product with the Color option defined as black will look like this in the payload:

  {
    ...
    "variant_options": [
        {
            "id": "069db350-8d41-11eb-f6a9-869155c00090",
            "name": "Color",
            "value": "black"
        }
    ]
    ...
  }

NOTE: It will sometimes happen that a product not involved in a variant product will have those properties populated in the payload. That means that this product used to be a variant (most likely parent) but the user turned it into a simple product. Variant options should not be used to determine if a product is a variant. Use variant_parent_id and has_variants instead.

Variant property inheritance

When reading a product's properties, it's important to know that variant children don't hold all the data related to them. Some of that data is inherited from the parent.
The following attributes of a product are inherited from the parent:

• Name
• Handle
• Description
• Has inventory
• Source
• Tags
• Product Categories
• Suppliers
• Brand
• Sales account code
• Purchase account code

The following attributes are associated directly with the variant product:

• Product codes
• Pricing
• Loyalty
• Supplier code and price
• Inventory
• Product
• Variant options
• Variant images
• Packaging
• Weights and dimensions

How to get all the variants

In order to load all members of a variant family, a GET request can be sent to https://<<domain_prefix>>.retail.lightspeed.app/api/3.0/products/{id} where id is the id of the parent variant.

How to create variants

See Creating variant products via the API for details.

How to delete variants

If you have a variant that you want to delete, you can send a DELETE request to https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/products/{id} where {id} is the product id of the variant you would like deleted.

If you would like to delete the entire variant family, you can append /all to the URL like so https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/products/{id}/all.

This cannot be undone.

Updating variants

See Updating existing variant products for details.

Gotchas

Variant updates and base_name

There are two name properties for variants. name and variant_name. Name represents the parent, and therefore the family and will be the same for every variant. variant_name represents the individual variant, and will be the base name plus any variant attributes seperated by /.

The variant_name field is read only. it can not be modified by the API.

For example, we have a variant product for an iphone case. The Product name will be iphone case while variant names will be iphone case / black and iphone case / blue.

For example: GET https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/products/{id}

{
    "includes": null,
    "data": {
      ...
        "name": "iPhone Case",
        "variant_name": "iPhone Case / Black"
      ...
    }
}

Handle and name

Handle and name are slightly different. The name represents the product family in a human readable way. The handle represents the slug for ecommerce integrations, and isn't used in normal operation outside those integrations. The handle can be provided in the create API, but it isn't required. If a handle isn't provided, it is generated based on the name making it URL friendly.

For example, iPhone Case becomes iphone-case.