Categories
Update your store categories while keeping control of their images.
What it does
The category importer updates the categories customers use to browse your store.
What customers see
Customers see the updated category names and hierarchy. Missing categories are hidden; a later import can restore them. Changes appear within about 5 minutes of uploading - reload an open storefront page to see them. See when changes appear.
When to use it
Use it to change the category tree, display order or category descriptions.
Before you upload
Always upload the complete category tree. An empty file or header-only file hides every category.
If the CSV has an IMAGE_URL header, every listed category image is replaced. A blank IMAGE_URL
cell clears the image. This 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.
If you manage category images in the admin panel, remove IMAGE_URL from the feed.
Each row adds a category or updates the category with the same category ID.
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.
The file supplies all fields of every category it lists. 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 above.
Read the shared CSV format before preparing your file.
Steps
- Open eCommerce → Importers.
- In Upload CSV, choose Import for Categories then use Pick CSV file to select your complete file.
- Review the replacement warning, then select Upload and replace.
What you'll see
The file appears in Import log as Pending, then Success or Failed. See when changes appear before checking your storefront.
If the file fails, ProConnect emails your store's email address with the reason and the rows to correct, and emails you again when a later Categories file succeeds. A run of failures is only emailed the first time. See Email notifications.
If something goes wrong
- Failed import: select View report, correct the reported rows and upload the complete file again. A validation error prevents the whole file from being applied.
- A category is missing from your storefront: its
PARENT_IDnames a category that is not in the file, or the categories point at each other in a loop. The file still imports, but that category is hidden from browsing and shows an Orphaned badge in eCommerce → Categories. Add the parent to the file, clear the parent on that row, or break the loop, then upload again. - An image disappears: check whether the file includes a blank IMAGE_URL cell; remove the column when managing images in the admin panel.
- Missing rows after a successful upload: restore them in the complete file and upload again. Check the replacement rules above before sending another file.
See the shared identifier matching rules when preparing your file.
Columns
Limits count characters after surrounding spaces are removed. A value over its limit fails that row, and the file is not applied. See the shared value limits.
Category tree
| Column | Required | Limit | Example | Notes |
|---|---|---|---|---|
CATEGORY_ID | Yes | 1-255 characters | drinks | Must contain a letter or digit. Stored in lowercase with any other characters replaced by hyphens, so Crisps & Snacks becomes crisps-snacks. If the same category appears more than once, the last row wins. |
TITLE | Yes | 1-255 characters | Drinks | The category name shown on the storefront and used in product search. |
PARENT_ID | No | Up to 255 characters | drinks | Must reference a CATEGORY_ID in the same file, and is converted the same way. Cycles are rejected. Blank means top level. |
ORDER | No | Whole number, 0 or greater | 10 | 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 | One of the four category types, in any letter case | CATEGORY | CATEGORY, PROMOTION, BADGE_ONE, or PREVIOUSLY_PURCHASED. Defaults to CATEGORY. See category types below. |
Content and images
| Column | Required | Limit | Example | Notes |
|---|---|---|---|---|
DESCRIPTION | No | No fixed limit | Still spring water | Category description. |
IMAGE_URL | No | Up to 2083 characters | https://example.com/image.jpg | See category image rules above. |
RESTRICTED_TYPES | No | Up to 255 characters | Leave blank | Currently unused by the storefront. |
Every file must contain the complete tree: a PARENT_ID that exists in your store 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.
Image recommendations
Use landscape 4:3 images, at least 800x600 and ideally 1200x900. Images that aren't 4:3 are cropped to fit the tile, so anything close to the edges may be cut off.
The same image is used for tiles and category banners, with different crops. Keep important subjects, text and logos near the centre.
Use a public HTTPS image URL. If an image is missing or cannot load, customers see your Default Category Image from Store Settings, or a centred image icon on a soft background if you have not set one.
Give each new picture a new address. A new address appears with the next category import, but changing the picture behind an address you have already used can leave customers seeing the old picture for up to a month.
Example CSV
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.