⚙️ Introduction

This job allows the creation and update of Assortments, and the linking or unlinking of Products and Variants via CSV import or API Connector.

You can:

• Create empty assortments
• Add or remove products in an assortment
• Add or remove specific variants in an assortment
• Combine product-level and variant-level logic within the same assortment

📂 Import model

CSV Structure

The CSV file must contain one row per operation (one product or one variant to link/unlink per row). Multiple rows can belong to the same assortment.

Two CSV structures are supported:

Existing structure (product only — retrocompatible)

Extended structure (product + variant)

📄

Template

You can use the following spreadsheet as a template to structure your import:

Assortments - Template

📘

The column Product External Id is optional. When it is empty, the presence of Variant External Id alone is sufficient to link the variant to the assortment.

API Connector

The API Connector sends data as a JSON payload. The JSON must always be a list of objects.

[
  {
    "assortmentExternalId": "string",
    "assortmentName": "string",
    "productExternalId": "string",
    "variantExternalId": "string",
    "unlink": false
  }
]

📋 Fields

⚠️

Assortment Name behavior

The Assortment Name field is not mandatory, but its behavior is specific:

• On creation — if not provided, the assortment is created with an empty name.
• On update — if not provided, the existing name is cleared.

It is strongly recommended to always provide the assortment name on both creation and update to avoid unintended data loss.

🧠 Key Business Rules

Linking logic

• An assortment is identified by its Assortment External Id. If it does not exist, it is created. If it exists, it is updated.
• To link a product (all its variants included): provide Product External Id, leave Variant External Id empty.
• To link a specific variant only: provide Variant External Id, leave Product External Id empty.
• When both Product External Id and Variant External Id are provided in the same row: the variant takes priority — only the variant is linked, the product is ignored for that row.
• When Product External Id and an unrelated Variant External Id are in the same row: both are linked independently (the product with all its variants, and the variant separately).

Unlinking logic

• Set Unlink to TRUE to remove a product or variant from an assortment.
• Unlinking a product removes all its variants from the assortment.
• Unlinking a variant when both Product External Id and Variant External Id are in the same row: only the variant is removed, the product is ignored for that row.
• Unlinking a product and an unrelated variant in the same row: both are removed independently.

Priority rule summary

🌟

Products = bulk inclusion — Variants = fine-grained control — Variants always override products when both are provided in the same row.

Common business scenarios

Scenario 1 — Include a whole product (all variants)

Link the product with all its variants to the assortment.

Scenario 2 — Include only specific variants of a product

Link only selected variants, excluding others.

Scenario 3 — Include a product but exclude one variant

Link the full product then unlink a specific variant.

Scenario 4 — Remove a product from an assortment

Unlink a product and all its variants.

Scenario 5 — Create an empty assortment

Create an assortment without linking any product or variant yet.

📌

Best Practices

✔️ Always provide the Assortment Name on both creation and update to avoid unintentional clearing of the name.

✔️ Use product-level linking for bulk operations and variant-level linking for fine-grained catalog control.

✔️ Remember that when both Product External Id and Variant External Id are in the same row, the variant always takes priority.