Loader Configuration Reference¶

This page provides a complete reference for the LoaderProcess configuration object. The configuration controls how the Loader processes your CSV data, including what entity types to create, how to map columns, and how to transform values.

For a getting-started guide, see Getting Started. For details on the preprocessing pipeline that runs on your data, see Preprocessing Pipeline.

Configuration Schema¶

The LoaderProcess configuration is a JSON object with the following top-level properties:

{
  "loadType": ["ITEM"],
  "fileLocation": "file-entity-id",
  "federatedMappings": { ... },
  "conditionalColumns": [ ... ],
  "propertiesToRemove": [ ... ],
  "workspaceIdentifier": "fall:2025",
  "assortmentSplit": { ... },
  "partialAssortmentUpdate": true,
  "assortmentItemDropField": "dropColumn",
  "shouldSkipAssortmentPublish": false,
  "loaderConfigurationId": "config-file-id"
}

Property Reference¶

`loadType` (required)¶

An array of strings specifying which entity types to create from the CSV data. The load type determines which processor handles your data and what validations are applied.

Value	Description
`ITEM`	Load global Item entities (families and options)
`PROJECT_ITEM`	Load ProjectItem entities into a Project. Must be paired with `ITEM`.
`ASSORTMENT`	Load AssortmentItem entities into Assortments. Must be paired with `ITEM`. Can also include `PROJECT_ITEM`.
`COLOR`	Load Color entities
`CUSTOM_ENTITY`	Load Custom Entity instances for a specific type
`SIZE_RANGE_TEMPLATE`	Load Size Range Template entities

Combining load types: Only ITEM supports combining with other types. Common combinations:

["ITEM"] -- Load only global items.
["ITEM", "PROJECT_ITEM"] -- Load items and add them to a project.
["ITEM", "PROJECT_ITEM", "ASSORTMENT"] -- Load items, add to a project, and assign to assortments.
["ITEM", "ASSORTMENT"] -- Load items and assign to assortments (project auto-detected from assortment).

`fileLocation` (required for API/SDK)¶

The ID of the uploaded CSV file entity. When using the CLI, this is set automatically from the file you provide. When using the API or SDK, you must first upload your CSV file and then provide the resulting file entity ID here.

See Getting Started > Upload Your CSV Data File for upload instructions.

`federatedMappings`¶

A key-value object that maps target property names to source CSV column names. This creates new columns by copying values from existing columns, or creates columns with static values for all rows.

{
  "federatedMappings": {
    "name": "Product Name",
    "itemFamilyFederatedId": "SKU",
    "itemOptionFederatedId": "Color Code",
    "originatingSystem": "My ERP"
  }
}

How it works:

If the value matches a CSV column name, values from that column are copied into a new column with the key's name.
If the value does not match any CSV column name, the literal value is set on all rows as a new column.
The original columns are preserved -- federated mappings add new columns without removing existing ones.
Mappings are applied early in the preprocessing pipeline (step 2), before conditional columns are evaluated.

Common mappings by entity type:

ItemsColorsCustom Entities

{
  "federatedMappings": {
    "name": "Style Name",
    "itemFamilyFederatedId": "Style Number",
    "itemOptionFederatedId": "SKU",
    "optionName": "Color Name"
  }
}

{
  "federatedMappings": {
    "federatedId": "Color Code",
    "name": "Color Name",
    "hex": "Hex Value",
    "red": "R",
    "green": "G",
    "blue": "B"
  }
}

{
  "federatedMappings": {
    "federatedId": "Vendor Code",
    "name": "Vendor Name"
  }
}

`conditionalColumns`¶

An array of column definitions that create new columns based on conditions or expressions. Conditions are evaluated as JavaScript expressions, with access to other column values via curly-brace interpolation.

interface ColumnDefinition {
  toProperty: string;
  fromProperty?: string;
  conditions?: ConditionalValues[];
  default?: any;
}

interface ConditionalValues {
  conditional: string;
  value: any;
}

Property	Type	Description
`toProperty`	`string`	The target column name to write to. Overwrites if already exists.
`fromProperty`	`string` (optional)	Copy the value from this column. Ignored if `conditions` are provided.
`conditions`	`array` (optional)	Array of condition/value pairs. First matching condition wins.
`default`	`any` (optional)	Value to use if no conditions match, or as a template expression.

Variable interpolation: Use {columnName} in both conditional expressions and value/default strings to reference values from the current row. If the value contains {, it is evaluated as a JavaScript template expression.

Examples¶

Set a static value (e.g., typePath):

{
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "item:product:apparel"
    }
  ]
}

Copy from another column:

{
  "conditionalColumns": [
    {
      "toProperty": "federatedId",
      "fromProperty": "externalCode"
    }
  ]
}

Conditional logic:

{
  "conditionalColumns": [
    {
      "toProperty": "region",
      "conditions": [
        {
          "conditional": "{countryCode} === 'US' || {countryCode} === 'CA'",
          "value": "North America"
        },
        {
          "conditional": "{countryCode} === 'UK' || {countryCode} === 'FR'",
          "value": "Europe"
        }
      ],
      "default": "Other"
    }
  ]
}

JavaScript expressions in default:

{
  "conditionalColumns": [
    {
      "toProperty": "itemFamilyFederatedId",
      "default": "{familyNumber}.split('-')[0]"
    },
    {
      "toProperty": "name",
      "default": "{familyNumber}.split('-')[0]"
    }
  ]
}

Evaluation order

Conditional columns are evaluated after federated mappings are applied, so you can reference columns that were created by federated mappings. See the Preprocessing Pipeline for the full execution order.

`propertiesToRemove`¶

An array of column names to strip from the CSV data before processing. Use this to remove columns that would otherwise cause warnings or be incorrectly mapped to properties.

{
  "propertiesToRemove": ["internalNotes", "tempCalculation", "legacyCode"]
}

Properties are removed in step 3 of the preprocessing pipeline, after federated mappings are applied but before type-based transformations.

`workspaceIdentifier`¶

The identifier of the Project (workspace) to load PROJECT_ITEM entities into. Required when loading PROJECT_ITEM without an assortmentSplit configuration (since the project cannot be inferred from an assortment).

You can find a project's identifier in the Hub UI: click the hamburger menu next to the project name, select "Configure Project", and view the identifier property.

{
  "loadType": ["ITEM", "PROJECT_ITEM"],
  "workspaceIdentifier": "fall:2025"
}

Project resolution priority

When loading project items, the system resolves the target project in this order:

workspaceIdentifier -- looks up workspace, then its project
assortmentSplit values with assortmentId -- looks up assortment, then its workspace's project
assortmentSplit values with assortmentIdentifier -- looks up assortment by identifier, then its workspace's project
assortmentId in the CSV data -- uses the first row's value

`assortmentSplit`¶

Configuration for splitting CSV rows across multiple assortments based on a column's value. Required when loading ASSORTMENT type.

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

Property	Type	Description
`fieldToSplitOn`	`string`	CSV column name whose values determine which assortment each row belongs to.
`values`	`array`	Array of value-to-assortment mappings.
`values[].value`	`string`	The column value to match on.
`values[].assortmentId`	`string` (optional)	The ID of the target assortment.
`values[].assortmentIdentifier`	`string` (optional)	The identifier of the target assortment.
`partialAssortmentUpdate`	`boolean` (optional)	If `true`, only add/drop specified items instead of replacing the full assortment. Default: `false`.
`addField`	`string` (optional)	CSV column name. Rows with `true` in this column are added. Used with partial updates.
`dropField`	`string` (optional)	CSV column name. Rows with `true` in this column are dropped. Used with partial updates.

For full assortment loading documentation, see Assortments.

`partialAssortmentUpdate`¶

A top-level boolean flag (alternative to assortmentSplit.partialAssortmentUpdate) that enables partial assortment updates. When true, items in the load file are added to the assortment without removing existing items.

`assortmentItemDropField`¶

A top-level string (alternative to assortmentSplit.dropField) specifying the CSV column that indicates which items should be dropped from the assortment during a partial update.

`shouldSkipAssortmentPublish`¶

When set to true, assortment item updates are written directly to the database without going through the publish workflow. This is faster but skips change history, summary recalculation, composite assortment updates, and the assortment|publish event.

See Assortments > Direct AssortmentItem Updates vs. Assortment Publish for details.

`loaderConfigurationId`¶

The ID of a pre-uploaded YAML or JSON file containing the LoaderProcess configuration. Use this to reuse a common configuration across multiple load processes without redefining it each time.

Complete Configuration Examples¶

Loading Items with Options¶

JSONYAML

{
  "loadType": ["ITEM"],
  "federatedMappings": {
    "name": "Style Name",
    "itemFamilyFederatedId": "Style Number",
    "itemOptionFederatedId": "SKU",
    "optionName": "Color Name"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "item:product:apparel"
    },
    {
      "toProperty": "optionGroup",
      "default": "color"
    }
  ]
}

loadType:
  - ITEM
federatedMappings:
  name: "Style Name"
  itemFamilyFederatedId: "Style Number"
  itemOptionFederatedId: "SKU"
  optionName: "Color Name"
conditionalColumns:
  - toProperty: typePath
    default: "item:product:apparel"
  - toProperty: optionGroup
    default: color

Loading Colors¶

JSONYAML

{
  "loadType": ["COLOR"],
  "federatedMappings": {
    "federatedId": "Color Code",
    "name": "Color Name",
    "hex": "Hex Value"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "color"
    }
  ]
}

loadType:
  - COLOR
federatedMappings:
  federatedId: "Color Code"
  name: "Color Name"
  hex: "Hex Value"
conditionalColumns:
  - toProperty: typePath
    default: color

Loading Custom Entities¶

JSONYAML

{
  "loadType": ["CUSTOM_ENTITY"],
  "federatedMappings": {
    "federatedId": "Vendor Code",
    "name": "Vendor Name"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "custom-entity:vendor"
    }
  ]
}

loadType:
  - CUSTOM_ENTITY
federatedMappings:
  federatedId: "Vendor Code"
  name: "Vendor Name"
conditionalColumns:
  - toProperty: typePath
    default: "custom-entity:vendor"

Loading Items into a Project and Split Assortments¶

JSONYAML

{
  "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-id-1"
      },
      {
        "value": "womens",
        "assortmentId": "assortment-id-2"
      }
    ]
  }
}

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-id-1
    - value: womens
      assortmentId: assortment-id-2

Loader Configuration Reference¶

Configuration Schema¶

Property Reference¶

loadType (required)¶

fileLocation (required for API/SDK)¶

federatedMappings¶

conditionalColumns¶

Examples¶

propertiesToRemove¶

workspaceIdentifier¶

assortmentSplit¶

partialAssortmentUpdate¶

assortmentItemDropField¶

shouldSkipAssortmentPublish¶

loaderConfigurationId¶

Complete Configuration Examples¶

Loading Items with Options¶

Loading Colors¶

Loading Custom Entities¶

Loading Items into a Project and Split Assortments¶

`loadType` (required)¶

`fileLocation` (required for API/SDK)¶

`federatedMappings`¶

`conditionalColumns`¶

`propertiesToRemove`¶

`workspaceIdentifier`¶

`assortmentSplit`¶

`partialAssortmentUpdate`¶

`assortmentItemDropField`¶

`shouldSkipAssortmentPublish`¶

`loaderConfigurationId`¶