Knowledge Base

Textile variants

This page details how textile variants are handled on Alkemics and how there are handled by the APIs.

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.

1. How textile variants are handled

Variants are not listed in the product list API, they can be directly found in the model data:

{
  "textileVariantList": [{
    "status": "ACTIVE",
    "updatedAt": "2019-01-01T00:00:00",
    "textileVariant": {
      "gtin": "01234567891011",
      "uuid": "c3bfbb24-e6e5-4a05-8de4-d661037e8aed",
      "version": {}
    }
  }, {
    "status": "INACTIVE",
    "updatedAt": "2019-01-01T00:00:01",
    "textileVariant": {
      "gtin": "01234567891012",
      "uuid": "afeea60c-f5dd-46a4-8130-e059d954c66d",
      "version": {}
    }
  }]
}
  • 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.
Attributes filled on the model have precedence over attributes filled in the variants.
If an attribute is filled on the model, its value should be applied on all variants, even if this field is also set on 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

2. How textile logistical hierarchies are handled

📘

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"
        }
      }
    }]
  }]
}
{
  "gtin": "MODEL_GTIN",
  "textileVariantList": [{
      "textileVariant": {
        "gtin": "VARIANT_A_GTIN"
      }
    },
    {
      "textileVariant": {
        "gtin": "VARIANT_B_GTIN"
      }
    },
    {
      "textileVariant": {
        "gtin": "VARIANT_C_GTIN"
      }
    }
  ],
  "logisticalHierarchies": [{
    "gtin": "CASE_GTIN",
    "isMainHierarchyUnit": false,
    "children": [{
        "gtin": "VARIANT_B_GTIN",
        "quantity": 5,
        "isMainHierarchyUnit": false,
        "version": {
          "kind": {
            "code": "x"
          }
        }
      },
      {
        "gtin": "VARIANT_A_GTIN",
        "quantity": 5,
        "isMainHierarchyUnit": false,
        "version": {
          "kind": {
            "code": "x"
          }
        }
      }
    ]
  }]
}

3. Creating new 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 wanted 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.

Updated 12 months ago