⚙️ Introduction

This job allows you to create and update Assortments, and to link or unlink Products and/or Variants by importing a CSV file through the Data Hub (SFTP).

This import can be used to:

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.

📂 Accepted File Structure

The CSV file must follow the structure below.

Existing structure (product only – retrocompatible)

Assortment External Id	name	Product External Id	unlink
123	assort-A	product-1
123		product-2

Extended structure (product + variant)

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-1
123		product-1	variant-2

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

📋 Fields

DJUST name	Description	Required on creation	Required on update	Editable	Default value	Type
`assortmentExternalId`	Assortment's external ID	✅	✅	❌	—	Text
`assortmentName`	Assortment name	❌	❌	✅	—	Text
`productExternalIds`	Associated product's external ID	❌	❌	✅	—	Text
`variantExternalIds`	Associated variants's external ID	❌	❌	✅	—	Text
`unlink`	Enables the possibility to unlink product/variants assortment(s)	❌	❌	✅	`false`	Boolean `TRUE`: Unlink `FALSE`: Link

Assortment name behavior

The field assortmentName is not mandatory for both creation and update.

However, its behavior is the following:

On creation

If name is not provided:

The assortment is created with an empty name.

On update

If name is not provided:

The existing name is cleared (deleted).

In other words, the name field is not partial:

When present → it is set.

When absent → it is reset.

🚧
Important
Even if the field is technically optional, it is strongly recommended to always provide the assortment name on both creation and update to avoid unintended data loss.

Linking logic (SFTP / CSV)

Each CSV row is interpreted as an operation to link (default) or unlink (delete=true) one target (product or variant) to/from an assortment.

Assortment (create / update)

An assortment is identified by Assortment External Id.
If the assortment does not exist → it is created.
If it exists → it is updated.
name is optional (but strongly recommended)
- when provided, it sets/updates the assortment name.

Example (create/update assortment metadata only — empty assortment):

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A

Behavior: Create empty assortment.

Link a product

To link a product, fill Product External Id.

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-1

Behavior:

The product "product-1" is linked to the assortment.
All variants of this product are included.

Link a variant

To link a variant, fill only Variant External Id.

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A		variant-2

Behavior:

Only "variant-2" is linked to the assortment.
All other product variants are not linked.

Link a product and its associated variant

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-1	variant-2

Behavior:

Only the variant is linked.
The product is ignored for this row.

📘
Variant has priority over product when both are present in the same row.

Link a product and an unrelated variant (same row)

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-A	variant-B2

Behavior:

Product "product-A" is linked. (All its variants are included)
Variant "variant-B2" is also linked. (Even though it belongs to a different product)

Unlinking logic (SFTP / CSV)

Unlinking is controlled via the unlink column.

Unlink a variant

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A		variant-2	true

Behavior:

"variant-2" is removed from the assortment.

Unlink a product (and all its variants)

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-1		true

Behavior:

The product "product-1" is removed from the assortment.
All its variants are removed as well.

Unlink a Variant while also providing its Product (same row)

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-1	variant-2	true

Behavior:

Only the variant is removed.
The product is ignored for this row.

Unlink a product and an unrelated variant (same row)

Assortment External Id	name	Product External Id	Variant External Id	unlink
123	assort-A	product-A	variant-B2	true

Behavior:

Product "product-A" is unlinked. (All its variants are removed)
Variant "variant-B2" is also unlinked. (Even though it belongs to a different product)

Product vs Variant — Resolution Rules (SFTP)

The following rules apply when importing CSV files via SFTP.

Case 1 — Product and Variant in the same row

Assortment External Id	name	Product External Id	Variant External Id
123		product-1	variant-2

Behavior:

Only the variant is processed.
The product is ignored for this row.
The system links:
- variant-2
The system does not link:
- the full product "product-1"
the other variants of "product-1"

➡️ Rule: Variant always has priority over Product when both are provided in the same row.

Case 2 — Product and Variant in different rows

Assortment External Id	name	Product External Id	Variant External Id	unlink
123		product-1
123			variant-2

Behavior:

First row:
- Links product "product-1"→ All its variants are included.
Second row:
- Explicitly links "variant-2"

Final result:

Product "product-1" is in the assortment.
All its variants are included.
"variant-2" is also included.

➡️ Rule: Each row is processed independently and cumulatively.

Case 3 — Product added, Variant removed

Assortment External Id	name	Product External Id	Variant External Id	unlink
123		product-1
123			variant-2	true

Behavior:

Product "product-1" is added (all variants included).
Variant "variant-2" is explicitly removed.

Final result:

Product "product-1" is in the assortment.
All its variants are included except "variant-2".

Case 4 — Product and its Variant in same row with unlink = true

Assortment External Id	Product External Id	Variant External Id	unlink
123	product-1	variant-2	true

Behavior:

Only the variant is removed.
The product is ignored.

Summary of Resolution Logic :

Situation	Result
Product + Variant in same row	Variant only
Product and Variant in different rows	Both applied
Product added, Variant removed	Product included, variant excluded
Product removed, Variant added	Product removed, variant included
Both provided with `unlink = true`	Variant removed only

Key Business Rules & Notes

Linking one or more products to an Assortment is done via productExternalIds.
Linking one or more variants to an Assortment is done via variantExternalIds.
Unlinking a product or variant from an Assortment is done by setting unlink: true.
A single product or variant can be linked to multiple Assortments with no limit.

🔗Useful Links:

Assortment management from Data Hub - Import API : Assortment import API

Assortment management from the Back Office : Assortments