Skip to content

AssortmentItems

Loading assortments means assigning Items to Assortments within a Project. An Item's membership in an Assortment is represented by an AssortmentItem entity.

Prerequisites

  • Items must be loaded (or already exist) before they can be assigned to assortments. Include ITEM in your loadType.
  • You must specify which assortment(s) to load into via assortmentSplit or by including assortmentId in the CSV data.
  • When also loading PROJECT_ITEM, the project is automatically resolved from the assortment's workspace.

Configuration

To load assortment data, include ASSORTMENT in the loadType array. This is always combined with ITEM and optionally with PROJECT_ITEM:

{
  "loadType": ["ITEM", "PROJECT_ITEM", "ASSORTMENT"]
}

Specifying Target Assortments

Using assortmentSplit

The assortmentSplit configuration lets you route CSV rows to different assortments based on a column's value. Even for a single assortment.

{
  "assortmentSplit": {
    "fieldToSplitOn": "gender",
    "values": [
      {
        "value": "mens",
        "assortmentId": "abc123"
      },
      {
        "value": "womens",
        "assortmentIdentifier": "fall2025:womens:global"
      }
    ]
  }
}

Properties:

  • fieldToSplitOn: The column name in the load file to use for splitting.
  • values: An array of objects specifying the value to split on and the assortment to load into.
    • value: The value in the fieldToSplitOn column to split on (e.g., "mens").
    • assortmentId: The ID of the assortment to load matching rows into.
    • assortmentIdentifier: The identifier of the assortment to load matching rows into. Can be combined with assortmentId within the assortmentSplit object.

How splitting works:

  1. The Loader groups rows by the value in the fieldToSplitOn column.
  2. Each group is matched to an assortment from the values array.
  3. Rows whose fieldToSplitOn value doesn't match any entry in values are not loaded into any assortment.
  4. Each assortment is loaded independently.

Using assortmentId in CSV Data

Alternatively, you can include an assortmentId column directly in your CSV. However, this approach has limitations:

  • Only the first row's assortmentId value is used for the entire load.
  • All items go to a single assortment (no splitting).
  • Only full loads are supported (no partial updates).

You can also set this via a conditional column:

{
  "conditionalColumns": [
    {
      "toProperty": "assortmentId",
      "default": "your-assortment-id"
    }
  ]
}

Full Assortment Load (Default)

A full assortment load replaces the assortment's contents with the items in your CSV. This means:

  • Items in the CSV that are not in the assortment are added.
  • Items in the CSV that are in the assortment are updated (if properties changed).
  • Items in the assortment that are not in the CSV are removed (deleted from the assortment).
  • Items that match and have no changes are left unchanged.

This is the default behavior when partialAssortmentUpdate is not set or is false.

Entity Comparison

For full loads, the Loader computes an entity comparison summary showing:

  • Adds: New items being added to the assortment
  • Updates: Existing items whose properties have changed
  • Deletes: Items being removed from the assortment
  • Unchanged: Items that match and have no property changes

This summary is available on the LoaderProcess entity after completion.

Example: Full Load into Multiple Assortments

Style Number,Style Name,Color,gender
STY-001,Classic Tee,Red,mens
STY-002,V-Neck Tee,Blue,mens
STY-003,Tank Top,White,womens
STY-004,Crop Top,Black,womens

{
  "loadType": ["ITEM", "PROJECT_ITEM", "ASSORTMENT"],
  "federatedMappings": {
    "name": "Style Name",
    "itemFamilyFederatedId": "Style Number"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "item:product:apparel"
    }
  ],
  "workspaceIdentifier": "fall:2025",
  "assortmentSplit": {
    "fieldToSplitOn": "gender",
    "values": [
      {
        "value": "mens",
        "assortmentId": "assortment-mens-id"
      },
      {
        "value": "womens",
        "assortmentId": "assortment-womens-id"
      }
    ]
  }
}

In this example:

  • STY-001 and STY-002 are loaded into the "mens" assortment.
  • STY-003 and STY-004 are loaded into the "womens" assortment.
  • Any items previously in these assortments but not in the CSV will be removed.

Partial Assortment Load

Partial loads let you add or remove specific items from an assortment without affecting other items already in it. This is useful when you want to incrementally update an assortment's contents.

Enable partial loads by setting partialAssortmentUpdate: true in the assortmentSplit configuration:

{
  "assortmentSplit": {
    "partialAssortmentUpdate": true,
    "dropField": "shouldDrop",
    "fieldToSplitOn": "region",
    "values": [
      {
        "value": "EMEA",
        "assortmentId": "emea-assortment-id"
      }
    ]
  }
}

Add and Drop Fields

With partial updates, you control which items are added and which are dropped using boolean columns in your CSV:

Config Property CSV Column Behavior
addField Rows with true in this column are added to the assortment
dropField Rows with true in this column are dropped (removed) from the assortment

Rules for partial updates:

  • Items marked for add that already exist in the assortment are treated as updates instead (properties are updated).
  • Items marked for drop that don't exist in the assortment are skipped.
  • Items not marked for either add or drop are added by default (when no addField is configured, all rows are treated as adds).
  • If only dropField is configured, all non-dropped rows are treated as adds.

Example: Partial Assortment Update

Style Name,Style Number,addItem,dropItem,gender
Classic Tee,STY-001,false,true,womens
V-Neck Tee,STY-002,true,false,womens
Tank Top,STY-003,true,false,womens

{
  "loadType": ["ITEM", "PROJECT_ITEM", "ASSORTMENT"],
  "federatedMappings": {
    "name": "Style Name",
    "itemFamilyFederatedId": "Style Number"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "item:product:apparel"
    }
  ],
  "workspaceIdentifier": "fall:2025",
  "assortmentSplit": {
    "partialAssortmentUpdate": true,
    "addField": "addItem",
    "dropField": "dropItem",
    "fieldToSplitOn": "gender",
    "values": [
      {
        "value": "womens",
        "assortmentId": "womens-assortment-id"
      }
    ]
  }
}

In this example:

  • STY-001 will be removed from the womens assortment (dropItem=true).
  • STY-002 and STY-003 will be added to (or updated in) the womens assortment (addItem=true).
  • Any other items already in the assortment remain untouched.

Direct AssortmentItem Updates vs. Assortment Publish

Overview

When loading assortment item data, the loader provides two approaches for updating assortment items:

  1. Publish (default) — Updates through the publish mechanism, generating full change history and triggering downstream processes.
  2. Direct API Updates — Updates AssortmentItems directly without triggering the full publish workflow.

Publish Workflow (Default Behavior)

By default, assortment item loads use the publish mechanism. This generates a complete change history and triggers all downstream processes.

Advantages:

  • Complete Audit Trail — All changes are recorded in AssortmentPublishChange history
  • Assortment Summaries — Summary statistics and aggregates are automatically recalculated
  • Composite Assortment Updates — Composite assortments that depend on the updated assortment are automatically recalculated
  • Event Triggers — The assortment|publish event is triggered, notifying downstream integrations and workflows
  • Version Tracking — Version names and comments can be associated with the changes

Direct Loader Update

You can update assortment items directly in the database without going through the publish workflow by setting shouldSkipAssortmentPublish: true.

Advantages:

  • Performance — Significantly faster as it skips additional publish processing steps
  • Lightweight — Reduced system overhead and resource consumption
  • Simpler — Direct API updates without triggering complex event chains

Limitations:

  • No Assortment History — Changes are not recorded in the AssortmentPublishChange history
  • No Assortment Summaries — Summary statistics and aggregates are not automatically recalculated
  • No Composite Assortment Updates — Composite assortments will not be automatically recalculated
  • No Event Trigger for Publish — The assortment|publish event is not triggered. Triggers for assortment item changes are still emitted (e.g. assortment-item|create).
  • No Version Tracking — Version names and comments cannot be associated with the changes

Enabling Direct Updates

Set shouldSkipAssortmentPublish: true in your loader configuration:

loadType:
  - ITEM
  - PROJECT_ITEM
  - ASSORTMENT
shouldSkipAssortmentPublish: true
assortmentSplit:
  fieldToSplitOn: season
  values:
    - value: "spring"
      assortmentId: "someAssortmentId"

{
  "loadType": [
    "ITEM",
    "PROJECT_ITEM",
    "ASSORTMENT"
  ],
  "shouldSkipAssortmentPublish": true,
  "assortmentSplit": {
    "fieldToSplitOn": "season",
    "values": [
      {
        "value": "spring",
        "assortmentId": "someAssortmentId"
      }
    ]
  }
}

When shouldSkipAssortmentPublish is true, the loader will:

  • Update assortment items directly in the database
  • Skip generating AssortmentPublishChange records
  • Skip recalculating assortment summaries and aggregates
  • Skip triggering composite assortment recalculations
  • Skip emitting the assortment|publish event

Default Behavior

If shouldSkipAssortmentPublish is not specified or is set to false, the loader will use the publish workflow (the complete, history-tracked approach).

Enabling Direct Updates for All Loads (Feature Flag)

You can enable direct updates for all loader processes in your organization by using a feature flag. Contact your VibeIQ administrator or support team to enable the LOAD_ASSORTMENT_SKIP_PUBLISH feature flag for your organization.

When this feature flag is enabled:

  • All assortment item loads will use direct updates by default
  • Individual loader processes can still opt-in to the publish workflow by setting shouldSkipAssortmentPublish: false in their configuration
  • This is useful for organizations that cannot modify their loader configuration for some reason. The feature flag is expected to be deprecated, so it is not intended for long-term use. The most robust way to ensure loads proceed as expected is to explicitly set the shouldSkipAssortmentPublish parameter in your loader configuration.

When to Use Each Approach

Use Direct Loader Update when:

  • Making frequent updates where full history is not required
  • Performance is critical and you have a high volume of changes
  • You don't need to trigger workflows on the assortment|publish event
  • You are working in isolated assortments without composite relationships

Use Publish Workflow when:

  • You need a complete audit trail of all changes
  • Downstream systems need to be notified of changes via events
  • The assortment is part of a composite assortment structure
  • You need to maintain summary statistics and aggregates
  • Version control and change comments are important for your process
  • You need to track who made changes and when
  • You make updates to assortments infrequently and use large bulk updates rather than small, frequent updates

For general item loading (the family/option model, required properties), see Loading Item Data. For project item loading, see Project Items. For the full configuration reference, see Loader Configuration Reference.