Understanding variants

Terminology

• Model: the model is the generic product that acts as a container of all its related variants. A product is considered a model when it contains one or more variants. The model is not a physical product and is not sold.
• Variant: a variant is a product that specifies a model, by overriding a certain number of attributes. A product is considered a variant when it is linked to a model.
• Model attributes: they have the same value for all the variants
• Variant attributes: they have a specific value for each variant. Note that those can vary from product to product.

What is a Variant

A variant is a declination of a specific model where some attributes will be override.

For example :
You have a product which is a tee-shirt. It has his own specificities like its composition and may have different sizes like S, M, L.
The tee-shirt is your model, the sizes are your variants.

When searching for the model, you will get its variants data as well :

{
  "gtin": "01234567891010",
  "textileVariantList": [{
    "status": "ACTIVE",
    "updatedAt": "2019-01-01T00:00:00",
    "textileVariant": {
      "gtin": "01234567891011",
      "version": {}
    }
  }, {
    "status": "INACTIVE",
    "updatedAt": "2019-01-01T00:00:01",
    "textileVariant": {
      "gtin": "01234567891012",
      "version": {}
    }
  }]
}

📘

Even if the Variants have GTINs, they are not listed in the product list API. When getting a model with the product API, you will get its Variants as well.

• status: indicates if the variant is ACTIVE or INACTIVE. An inactive variant is no longer sold and is kept for history-related reasons.
• updatedAt specifies when the variant was last added in the list, or when its status was last updated.
• textileVariant is a view of the variant product. Its content is similar to other product type links:
  • version: this attribute contains a subset of the fields of the variant product:
    • updatedAt: the last date at which the variant was updated
    • it contains all the attributes that can have a value specified for variants.

❗️

Handling model and variant attributes

These attributes can be filled either on the model for all variants, or on each variant independently.
If an attribute is filled for both the model and the variant, the different values will appear in the product data.
Please note that you will only see the model value in the UI as its value will have precedence over attributes filled in the variants.

Attributes that can be specified on variants are listed on the Attributes page. They are highlighted with:

Value can be customised for textile variants: yes

Textile Variant

The notion of Variant is brought by the textile industry. Therefore, Variant refers to Textile Variant.

Textile Logistical Hierarchies

📘

Logistical hierarchies

If you have not already, please read the Understand logistical trees page.

All textile products are contained in cases, optionally contained in a pallet.

We currently support two types of logistical hierarchies:

• Standard hierarchies: the case content is fixed, every variant contained in the case is listed with its own quantity.
• Generic hierarchies: the case content is chosen when ordered. The case only contains the model and rules defining its composition:
  • subQuantity: the multiple by which each variant can be ordered. This is a denominator of the quantity of the model in the case.
  • allowedTextileColorTextList: the list of variant colors that can be included in the case. This is a list of strings referencing data of the attribute colorDescription.
  • allowedTextileSizeTextList: this list of variant sizes that can be included in the case. This is a list of strings referencing the codes of the attributes: genericTextileSizeList, braSizeList, shoeSizeList, gloveSizeList, babyClothesSizeList, confectionSizeList, babyChildSizeList, headCircumferenceSizeList, sockSizeList, duvetCoverSizeList, fittedSheetSizeList, pillowCaseSizeList, bedSheetSizeList.

For both types of hierarchies, the main product is the model, in the List Product API, an attribute isMainHierarchyUnit is added on each unit to help identify the main product. This can be used to differentiate the two types since standard hierarchies do not contain the model hence all their products have this attribute set to false.

Below are examples of each type. Note that those examples contain minimal information required for understanding, if using Inbound API to create or update, more attributes will be required.

{
  "gtin": "MODEL_GTIN",
  "textileVariantList": [{
      "textileVariant": {
        "gtin": "VARIANT_A_GTIN",
        "version": {
          "colorDescription": [{
            "data": "red"
          }],
          "genericTextileSizeList": [{
            "genericTextileSizeCode": {
              "code": "L"
            }
          }]
        }
      }
    },
    {
      "textileVariant": {
        "gtin": "VARIANT_B_GTIN",
        "version": {
          "colorDescription": [{
            "data": "blue"
          }],
          "genericTextileSizeList": [{
            "genericTextileSizeCode": {
              "code": "S"
            }
          }]
        }
      }
    },
    {
      "textileVariant": {
        "gtin": "VARIANT_C_GTIN",
        "version": {
          "colorDescription": [{
            "data": "green"
          }],
          "genericTextileSizeList": [{
            "genericTextileSizeCode": {
              "code": "S"
            }
          }]
        }
      }
    }
  ],
  "logisticalHierarchies": [{
    "gtin": "CASE_GTIN",
    "isMainHierarchyUnit": false,
    "version": {
      "subQuantity": 5,
      "allowedTextileColorTextList": ["red", "green"],
      "allowedTextileSizeTextList": ["L", "S"]
    },
    "children": [{
      "gtin": "MODEL_GTIN",
      "isMainHierarchyUnit": true,
      "quantity": 10,
      "version": {
        "kind": {
          "code": "x"
        }
      }
    }]
  }]
}

Manage your Variants

The Inbound API will allow you to create new variants and update existing ones by updating the model.

The input format is exactly the same as the output format:

{
  "textileVariantList": [{
      "status": "ACTIVE",
      "textileVariant": {
        "gtin": "01234567891011",
        "version": {}
      }
    }
  ]
}

The status is optional.
To add a new variant, add a new item to the list, if the variant product does not already exist, it will be created, otherwise it will be updated.
To remove a variant, change its status to INACTIVE, or completely remove it from the list depending on expected behaviour.

📘

Updating variant attributes

Variant attributes can be modified either by being specified in textileVariantList[*].textileVariant.version or by being updated on its own.
If updating via the model, not all attributes have to be sent. Only the sent attributes are updated, others are left untouched. To remove a field, send the attribute with null.