Guide · Categories import

Categories

Categories are addressed by their full path rather than by id, so a spreadsheet can build, rename or move a whole tree. The one thing to read before you write anything: BigCommerce deletes a category's descendants along with it, without warning.

1. The Category Path column

This is the most important column. It defines where the category sits in the hierarchy, using / as the separator.

Electronics                        → root-level category
Electronics/Phones                 → child of "Electronics"
Electronics/Phones/Samsung         → child of "Electronics/Phones"
Fashion/Men/Shirts                 → 3 levels deep

2. Commands

Command	Description	Behaviour
NEW	Create a new category.	Fails if the category path already exists.
UPDATE	Update an existing category.	Fails if the category path does not exist. Only updates provided fields.
MERGE	Create or update.	The default. If the path exists it updates; if not, it creates.
DELETE	Delete a category.	Refused if it has sub-categories, because BigCommerce deletes those too. Set `Cascade` to true, or list the sub-categories with DELETE as well.
REPLACE	Refused for categories.	Fails the row. Re-creating a category would destroy its sub-categories and every product assignment. Use UPDATE.
IGNORE	Skip this row.	Does nothing, and is recorded as skipped rather than as a success. Useful for commenting out rows.

3. All supported columns

CSV column	BigCommerce field	Required	Description
`Command`	—	Optional	Action to take: NEW, UPDATE, MERGE, DELETE, IGNORE. Default MERGE.
`Category Path`	—	Required	Full path of the category using `/` as the separator, e.g. Electronics/Phones/Samsung. Determines hierarchy.
`Description`	`description`	Optional	HTML description of the category.
`Is Visible`	`is_visible`	Optional	true or false. Controls storefront visibility.
`Image URL`	`image_url`	Optional	Publicly accessible image URL for this category.
`Page Title`	`page_title`	Optional	SEO page title. Defaults to the category name.
`Meta Keywords`	`meta_keywords`	Optional	Comma-separated SEO keywords, e.g. "phones,mobile,samsung".
`Meta Description`	`meta_description`	Optional	SEO meta description.
`Search Keywords`	`search_keywords`	Optional	Comma-separated keywords for store search, max 255 characters.
`Sort Order`	`sort_order`	Optional	Integer. A lower number sits higher in the menu.
`Default Product Sort`	`default_product_sort`	Optional	One of use_store_settings, featured, newest, best_selling, alpha_asc, alpha_desc, avg_customer_review, price_asc, price_desc. Friendly spellings are accepted ("Best Selling", best-selling); anything else fails the row and names the allowed values.
`Layout File`	`layout_file`	Optional	Theme template for this category, e.g. category.html.
`Custom URL`	`custom_url`	Optional	Storefront path. The leading and trailing slashes are added for you.
`Category ID`	`id`	Optional	BigCommerce category ID. With UPDATE and a different `Category Path`, this moves the category and its whole subtree.
`Category Name`	`name`	Optional	The display name. Omit it and the last segment of `Category Path` is used; give it and the leaf is renamed. There is no plain "Name" column — that header is ignored.
`Cascade`	—	Optional	true lets a DELETE remove a category that still has sub-categories. BigCommerce deletes the whole subtree, so this has to be said explicitly.
`Metafield: ns.key`	`metafields`	Optional	One column per metafield, e.g. "Metafield: forix.season". No dot means the `custom` namespace.
`Metafield Command`	—	Optional	MERGE (default) adds and updates the listed metafields; DELETE removes just those; REPLACE makes the listed ones the only ones.

4. Example file

Command,Category Path,Category Name,Description,Is Visible,Image URL,Page Title,Meta Keywords,Meta Description,Sort Order
NEW,Electronics,,<p>All electronics</p>,true,,Electronics,electronics,Browse all electronics,1
NEW,Electronics/Phones,,<p>Smartphones and more</p>,true,,,phones mobile,,2
NEW,Electronics/Phones/Samsung,Samsung Phones,<p>Samsung collection</p>,true,,Samsung Phones,samsung,,3
NEW,Electronics/Laptops,,<p>Laptops and notebooks</p>,true,,,,,
MERGE,Fashion,,,true,,,,,
MERGE,Fashion/Men,Men's Fashion,,true,,,,,
UPDATE,Electronics,,<p>Updated electronics description</p>,,,,,,
DELETE,Fashion/Men,,,,,,,,

5. Import behaviour

Parents must exist — a row whose parent path is not in BigCommerce, and not earlier in the same file, fails with "Parent does not exist". Put the parent in the file; rows are sorted so parents are created first, so the order you write them in does not matter.
Deleting a branch — BigCommerce deletes a category's whole subtree along with it, silently. So a DELETE row for a category that still has sub-categories is refused unless it sets Cascade to true, and the message says how many would go. Alternatively list the sub-categories with DELETE too — they are processed deepest-first, so the parent is emptied before it goes.
Moving and renaming — give Category ID with a different Category Path to move a category; its descendants move with it. Category Name renames the leaf. Either way, a later row in the same file can refer to the category, or its children, by the new path.
Blank cells never overwrite — a column you leave out, or leave empty, is not sent. A cell holding only spaces counts as empty too, so it cannot wipe a stored value.
Check before you run — the file check reports any column the importer does not recognise, with a suggestion for a likely typo. A dry run then previews every row without writing anything.

6. BigCommerce's own limits

16,000 categories per store.
8 levels deep (A/B/C/D/E/F/G/H).
A category name is at most 50 characters.
Rows are sorted parents-first for you, so a file does not need to be in any particular order.