Categories
Category CSV format, validation, update behaviour, and image handling.
Overview
The category importer is a full category snapshot for one store. Each successful import updates the active category tree for that store.
The background job processes uploaded category files about every 5 minutes. Storefront changes can take another 10-20 minutes to appear.
File format
- Header row required. Headers are case-insensitive.
- Unknown columns are ignored. Duplicate headers are rejected.
- Files must be UTF-8. A leading UTF-8 BOM is allowed.
Columns
| Column | Required | Rules |
|---|---|---|
CATEGORY_ID | Yes | 1-255 characters. Lowercased by the importer. If the same category appears more than once, the last row wins. |
TITLE | Yes | 1-255 characters. The category name shown on the storefront and used in product search. |
PARENT_ID | No | Must reference a CATEGORY_ID in the same file. Cycles are rejected. Blank means top level. |
DESCRIPTION | No | Category description. |
IMAGE_URL | No | Maximum 2083 characters. See category image rules below. |
ORDER | No | Integer 0 or greater. Defaults to 0. Categories with an order of 1 or more are listed first, in ascending order; categories left at 0 follow alphabetically. |
TAXONOMY_TYPE | No | CATEGORY, PROMOTION, BADGE_ONE, or PREVIOUSLY_PURCHASED. Defaults to CATEGORY. See category types below. |
RESTRICTED_TYPES | No | Currently unused by the storefront. |
Every file must contain the complete tree: a PARENT_ID that only exists in the database, but not in the current file, is a validation error.
Category types
TAXONOMY_TYPE controls what a category tile does on the storefront:
CATEGORY- a normal category. Opens its subcategories or product list.PROMOTION- opens the store's promoted products.BADGE_ONE- opens products carrying the store's second promotion badge.PREVIOUSLY_PURCHASED- opens the products the signed-in customer has bought before.
Validation
Category imports are all-or-nothing. If one row fails validation, the whole file is rejected.
When validation fails, the Import log shows a failure report with the rejected rows and reasons.
How updates are applied
Rows in the file are upserted as active categories.
Active categories missing from the file are deactivated. Their stored fields, including image, are preserved and are restored if that category is reactivated by a later import.
Every import rewrites all fields of every category in the file. Leaving out an optional column resets that field on every listed category - a missing ORDER column resets ordering to 0, a missing TAXONOMY_TYPE column resets types to CATEGORY, and a missing PARENT_ID column makes every category top level. The only exception is IMAGE_URL, described below.
A file that is valid but contains no data rows counts as an empty snapshot and deactivates every category for the store. Always send the complete tree.
Category images and IMAGE_URL
If the CSV has an IMAGE_URL header, the feed owns category images. Every category in the file
has its image overwritten. A blank IMAGE_URL cell clears the image. This silently replaces
images set in the admin panel.
If the CSV does not have an IMAGE_URL header, category images are untouched. Images set in the admin panel survive imports.
Rule: if you manage category images in the admin panel, remove IMAGE_URL from the feed.
Image recommendations
Use landscape 4:3 images, at least 800x600 and ideally 1200x900.
Keep the subject centred. Category tiles use a gradient and overlay the category title in white at the bottom.
IMAGE_URL can be any public https URL. The importer stores the URL exactly as supplied. If the URL is broken or the image cannot load, the storefront falls back to a placeholder.
Examples
Category CSV without IMAGE_URL. Existing images are kept.
CATEGORY_ID,TITLE,PARENT_ID,DESCRIPTION,ORDER
drinks,Drinks,,All drinks,10
soft-drinks,Soft Drinks,drinks,Bottled and canned soft drinks,20
water,Water,drinks,Still and sparkling water,30Category CSV with IMAGE_URL. Images are overwritten. The blank cell clears the image for soft-drinks.
CATEGORY_ID,TITLE,PARENT_ID,DESCRIPTION,IMAGE_URL,ORDER
drinks,Drinks,,All drinks,https://cdn.example.com/categories/drinks.jpg,10
soft-drinks,Soft Drinks,drinks,Bottled and canned soft drinks,,20
water,Water,drinks,Still and sparkling water,https://cdn.example.com/categories/water.jpg,30Download the sample category CSV to use as a template.