Skip to content

Load ProjectItems

A ProjectItem ties an Item to a Project. While Item data is global, ProjectItem data is specific to a project (e.g., a season). The same item can exist in multiple projects with different project-level property values. This is typically considered seasonal data that can change season over season — if an item is carried over into a following season, the ProjectItem data from the prior season will not necessarily be the same.

When you include PROJECT_ITEM in your loadType, the Loader will create or update ProjectItem entities into the target project.

Load Type Configuration

Include PROJECT_ITEM in the loadType array alongside ITEM:

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

You can also combine with ASSORTMENT to load into assortments at the same time:

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

Specifying the Target Project

The Loader needs to know which project to load project items into. There are several ways to specify this, resolved in the following priority order:

The most explicit way to specify the target project. Provide the project's identifier:

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

The Loader looks up the workspace by this identifier, then resolves its associated project.

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.

2. Via Assortment (Automatic)

When also loading into assortments, the project is automatically resolved from the assortment's workspace. No additional configuration is needed.

From assortmentId: If an assortmentId is provided (via assortmentSplit or the CSV data), the Loader fetches the assortment, finds its workspace, and resolves the project.

From assortmentIdentifier: If only assortmentIdentifier is provided, the Loader fetches the assortment by identifier, then resolves the workspace and project.

{
  "loadType": ["ITEM", "PROJECT_ITEM", "ASSORTMENT"],
  "assortmentSplit": {
    "fieldToSplitOn": "region",
    "values": [
      {
        "value": "EMEA",
        "assortmentId": "emea-assortment-id"
      }
    ]
  }
}

In this case, the project is automatically determined from the EMEA assortment's workspace.

CSV Structure

Project item CSV files use the same flat structure as item loads. Properties specific to the ProjectItem entity type are applied at the project level, while Item properties are applied globally.

Style Name,Style Number,Seasonal Status,Target Delivery
Classic Tee,STY-001,Active,2025-03-15
V-Neck Tee,STY-002,Carry Over,2025-04-01
Tank Top,STY-003,New,2025-05-15

Properties that exist on both Item and ProjectItem entity types are resolved based on the property's level designation (Family, Option, All, Override).

Complete Example

Style Name,Style Number,Seasonal Status,Target Price
Classic Tee,STY-001,Active,29.99
V-Neck Tee,STY-002,Carry Over,34.99
Tank Top,STY-003,New,24.99

{
  "loadType": ["ITEM", "PROJECT_ITEM"],
  "federatedMappings": {
    "name": "Style Name",
    "itemFamilyFederatedId": "Style Number"
  },
  "conditionalColumns": [
    {
      "toProperty": "typePath",
      "default": "item:product:apparel"
    }
  ],
  "workspaceIdentifier": "fall:2025"
}

loadType:
  - ITEM
  - PROJECT_ITEM
federatedMappings:
  name: "Style Name"
  itemFamilyFederatedId: "Style Number"
conditionalColumns:
  - toProperty: typePath
    default: "item:product:apparel"
workspaceIdentifier: "fall:2025"

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