Guide · Redirects import

Redirects

Bulk-import 301 redirects into a BigCommerce store from a spreadsheet. They are written through a single upsert endpoint, so they cannot be duplicated and a re-run changes nothing the second time — and they are the only entity here written in batches rather than one call per row.

1. Commands

Command	Description	Behaviour
MERGE	Create or update a redirect.	The default. An idempotent upsert, matched on `From Path` plus `Site ID`.
NEW	Same as MERGE.	BigCommerce offers one upsert endpoint for redirects, so NEW and UPDATE behave like MERGE rather than failing.
UPDATE	Same as MERGE.	As above — matched on `From Path` plus `Site ID`.
DELETE	Delete a redirect.	Uses `Redirect ID` if provided, otherwise looks the redirect up by `From Path`.
REPLACE	Behaves as MERGE.	Redirects are written as a batch upsert, so there is nothing to delete and re-create. This is the one entity that does not refuse REPLACE.
IGNORE	Skip this row.	Does nothing, and is recorded as skipped rather than as a success.

2. Destination types

For entity-based types — product, category, brand, page, post — supply the To Entity ID and BigCommerce resolves the destination URL itself. For a plain address, supply To URL.

To Type	To Entity ID means	To URL
`product`	BigCommerce product id — required	Leave empty; BigCommerce resolves it
`category`	BigCommerce category id — required	Leave empty; BigCommerce resolves it
`brand`	BigCommerce brand id — required	Leave empty; BigCommerce resolves it
`page`	BigCommerce page id — required	Leave empty; BigCommerce resolves it
`post`	BigCommerce blog post id — required	Leave empty; BigCommerce resolves it
`url`	Leave empty	Required — a path or an address, e.g. /new-page or https://example.com

3. All columns

CSV column	Required	Description
`Command`	Optional	MERGE \| NEW \| UPDATE \| DELETE \| IGNORE. Default MERGE.
`Redirect ID`	Optional	BigCommerce redirect id. Provide it for DELETE to skip the path lookup.
`From Path`	Required	The old path to redirect from, e.g. /old-product-url.
`Site ID`	Optional	BigCommerce storefront site id. Leave it out and your store's own site is used — it is usually not 1, so guessing would fail.
`To Type`	Optional	product \| category \| brand \| page \| post \| url.
`To Entity ID`	Conditional	Required for product, category, brand, page and post — the BigCommerce id of the thing to send visitors to.
`To URL`	Conditional	Required when `To Type` is url — the row is refused without it. Relative (/new-page) or absolute (https://example.com).
`Full Destination URL`	Optional	Written by the export for information only; BigCommerce computes it. The importer ignores it, which is why re-importing an exported file does not flag it as an unknown column.

4. Example file

Command,Redirect ID,From Path,To Type,To Entity ID,To URL
MERGE,,/old-product,product,101,
MERGE,,/old-category,category,25,
MERGE,,/moved-page,url,,/new-page/
MERGE,,/external,url,,https://example.com
DELETE,1001,,,,
DELETE,,/old-to-remove,,,

5. Things worth knowing

From Path should start with /, e.g. /old-product-url.
Every entity type needs an id. A product redirect with no To Entity ID is rejected by BigCommerce with a message that names neither the field nor the reason, so the row is failed first with the missing column named.
Leave Site ID blank unless you run several storefronts. Your store's own site id is read once per batch — it is usually not 1, so a guess would be rejected outright.
Deleting uses Redirect ID if you give one, otherwise it looks the redirect up by From Path. Supplying the id is faster.
Redirects are sent in batches rather than one call per row, so a large file is a handful of requests. Each row still gets its own result line.
Export first to get every existing redirect id before making bulk changes.
The exported Full Destination URL column is reference only — it is ignored on the way back in.
Check before you run. The file check flags any column that would be ignored, and a dry run previews every row — including which destination each would get — without writing anything.