CSV Import

CSV Import is the fastest way to apply SKUs, descriptors, and {val:KEY} metadata to a large batch. Drop 200 images from a shoot, drop a 200-row CSV, and every row is assigned in one click.

When to use it

• You have a PIM or product spreadsheet with rows-per-image metadata already.
• You have a 50+ row SKU assignment that would take a half-hour to type manually.
• Your filename template uses {val:KEY} tokens that resolve from per-image data (e.g. the E-commerce starter template).

If you only need to bucket a handful of images together, manual groups (the Group button in the selection toolbar) are faster. CSV is for the cases where filename metadata lives outside the workspace and you need it on dozens or hundreds of rows in one shot.

The three-step wizard

1. 1

   Upload CSV

   Drop a CSV or click to pick one. The wizard displays the first row and lets you confirm whether the file has a header row (defaults to yes; toggle off for headerless CSVs). Supported encodings: UTF-8 (including BOM), UTF-16, Windows-1252.

2. 2

   Map columns

   The wizard auto-detects which columns are the filename, sku, descriptor, and group based on header names (case-insensitive match against file, filename, image, sku, product, handle, descriptor, view, group, bucket, etc.). Every remaining column is surfaced as an available metadata key.

   Change any mapping from the dropdown. Drop down each unmapped column individually, or map it to metadata → KEY where KEY becomes the name used in {val:KEY} tokens. The reserved key group populates manual-group bucket membership (see Manual groups).

3. 3

   Review matches

   The review step shows every workspace image with the CSV row that matched it (if any). Matches are made by comparing the CSV's filename column to each image's original name. Unmatched images are flagged with a yellow badge; unmatched CSV rows are listed below.

   Confirm to apply. Every matched image gets its mapped metadata values (sku, descriptor, group, and any custom keys) written in one store update.

Match semantics

Matching is case-sensitive and extension-sensitive by default. IMG_4821.JPG does not match img_4821.jpg. The wizard offers a Case-insensitive checkbox at the review step that relaxes this, useful when the CSV came from a case-normalizing tool.

Exact filename matching is deliberate — fuzzy matching would silently assign the wrong SKU to a near-duplicate filename, which is impossible to notice after the fact. If your filenames don't line up, rename the CSV column to match before importing.

The metadata bag

Every image gets a flat Record<string, string> metadata bag after import. Keys are the lowercased, hyphenated versions of the CSV column headers you mapped as metadata. Values are passed through the same sanitization as descriptors before being stored.

Metadata is preserved across:

• Format Builder edits and ad-hoc format changes.
• Template applications (templates do not clear metadata).
• Session restores (the bag is persisted to IndexedDB alongside the image).

Metadata is cleared when you reset the workspace via the Start Over button. There is no per-group bulk-clear action; to wipe a single key on a group, multi-select the rows and use Set Metadata → KEY with an empty value.

Using metadata in filenames

Once metadata is loaded, any template's format string can reference {val:KEY}. See the Token reference for the full syntax, including the default= fallback.

Example CSV

For a shoot where you have a brand, product, and color for every file:

filename,sku,descriptor,brand,product,color
IMG_001.jpg,nike-001,front,nike,airmax-90,black
IMG_002.jpg,nike-001,side,nike,airmax-90,black
IMG_003.jpg,nike-002,front,nike,airmax-90,red

Apply the E-commerce starter template (format {val:brand}-{val:product}-{val:style}-{val:color}-{val:view}-{seq:2}{ext}) and the filenames become nike-airmax-90--black--01.jpg (with style and view rendering empty because the CSV didn't have them). Add those columns and they fill in.