BigCommerce has a Data Migration app for standard WooCommerce stores, and for a clean catalog it may be all you need. But when you have custom fields, messy categories, or you want full control over URLs, importing through the V3 Catalog API is often the safer route.
This post shows the core pattern: pull data from WooCommerce, create the structure BigCommerce expects first, then import products with their URLs intact.
The one rule that shapes everything
BigCommerce's documentation states that categories and brands must exist in the store before you import products, and products are assigned to them by numeric ID, not by name. WooCommerce gives you names and slugs. So the migration has two phases:
- Create categories (and brands), and build a
name -> BigCommerce IDmap. - Import products using those IDs.
If you reverse the order, the import fails or products land uncategorised.
Step 0: Prepare credentials and settings
In the BigCommerce control panel, create an API account with Products: modify scope. You will get a store hash and an access token.
Before importing, align store settings with your source data: weight units, dimensions, currency and timezone. A store set to kilograms receiving pounds is a quiet way to ship wrong data.
Step 1: Pull data from WooCommerce
import requests
WC = "https://your-store.com/wp-json/wc/v3"
WC_AUTH = ("ck_xxx", "cs_xxx") # read-only keys
def wc_fetch(endpoint, **params):
page, out = 1, []
while True:
r = requests.get(f"{WC}/{endpoint}", auth=WC_AUTH,
params={"per_page": 100, "page": page, **params},
timeout=30)
r.raise_for_status()
batch = r.json()
if not batch:
return out
out += batch
page += 1
wc_categories = wc_fetch("products/categories")
wc_products = wc_fetch("products", status="publish")
Step 2: Create categories and build the ID map
WooCommerce categories form a tree (parent points to a parent ID), so create parents before children.
STORE_HASH = "abc123"
BC = f"https://api.bigcommerce.com/stores/{STORE_HASH}/v3"
HEADERS = {
"X-Auth-Token": "your_bc_token",
"Content-Type": "application/json",
"Accept": "application/json",
}
wc_to_bc_category = {} # WooCommerce category ID -> BigCommerce category ID
def create_category(c):
parent = wc_to_bc_category.get(c["parent"], 0)
payload = {
"name": c["name"],
"parent_id": parent,
"custom_url": {"url": f"/{c['slug']}/", "is_customized": True},
}
r = requests.post(f"{BC}/catalog/categories", headers=HEADERS, json=payload)
r.raise_for_status()
wc_to_bc_category[c["id"]] = r.json()["data"]["id"]
# parents first
for c in wc_categories:
if c["parent"] == 0:
create_category(c)
for c in wc_categories:
if c["parent"] != 0:
create_category(c)
This simple two-pass loop handles two levels. For deeper trees, loop until every category has an ID. Also confirm in the current BigCommerce docs which category endpoint your store should use, since catalog category endpoints have evolved.
Step 3: Import products
import time
def to_bc_product(p):
return {
"name": p["name"],
"type": "physical",
"sku": p.get("sku", ""),
"description": p.get("description", ""),
"price": float(p.get("regular_price") or p.get("price") or 0),
"weight": float(p.get("weight") or 0),
"categories": [
wc_to_bc_category[c["id"]]
for c in p.get("categories", [])
if c["id"] in wc_to_bc_category
],
"inventory_tracking": "product" if p.get("manage_stock") else "none",
"inventory_level": p.get("stock_quantity") or 0,
"is_visible": True,
"custom_url": {"url": f"/product/{p['slug']}/", "is_customized": True},
}
for p in wc_products:
if p["type"] != "simple":
continue # variable products need variants, handled separately
r = requests.post(f"{BC}/catalog/products", headers=HEADERS,
json=to_bc_product(p))
if r.status_code == 429: # rate limited: wait and retry once
time.sleep(2)
r = requests.post(f"{BC}/catalog/products", headers=HEADERS,
json=to_bc_product(p))
if not r.ok:
print("FAILED", p["slug"], r.status_code, r.text[:200])
Three things worth noticing:
-
custom_urllets you set the product's path yourself. Reusing the WooCommerce path (here/product/{slug}/) means those URLs can stay the same, so you need far fewer redirects. Verify the exact path rules against BigCommerce's current API reference. -
Rate limits are real. Handle
429responses, and log failures instead of stopping the whole run. - Variable products need variants and options. Treat them as a second pass once simple products import cleanly.
Step 4: Images, customers and orders
Images can be attached through the product images endpoint using a public image_url. Keep the alt text, because it feeds image SEO.
For customers and order history, the Data Migration app can import them from WooCommerce, with a limit of 500,000 total records and error reporting afterwards. A hybrid is common: import the catalog through the API for control, then use the app or a dedicated import for customers and orders.
Customer passwords do not carry over. Plan a password-reset or account-activation email and warn customers beforehand.
Step 5: Redirects for everything that still changes
If you preserved product and category paths with custom_url, most of your traffic URLs survive unchanged. You still need 301 redirects for anything that moves: pages, blog posts, tag archives, and any category whose path changed.
Rules that save rankings:
- One hop only. Old URL to final URL, never a chain.
- Redirect to the closest equivalent, not the homepage.
- Test against a crawl. Every indexable URL on the old site should return a 301 to a 200, or a 200 directly.
Step 6: Verify before launch
- Crawl the staging store and diff titles, descriptions, H1s and canonicals against your old crawl
- Place test orders with every payment method, discount code and shipping rule
- Confirm product structured data (price, availability, reviews) still renders
- Submit the new sitemap after launch and watch Search Console daily for the first two weeks
Common mistakes
- Importing products before categories and brands exist
- Mixing up weight or dimension units between the two stores
- Letting BigCommerce auto-generate new URLs and skipping redirects
- Migrating dead products, unused categories and obsolete data
- Launching without testing the complete checkout
Wrapping up
The pattern is simple: build the structure first, import with IDs, preserve URLs where you can, redirect what you cannot, and verify with a crawl. Scripts like these are a starting point; every real catalog has edge cases like bundles, subscriptions and custom fields.
If you would rather have a team handle it, the company I work for, RW Infotech, describes how it approaches this on its WooCommerce to BigCommerce migration page.
What was the hardest part of your last store migration: variants, URLs or customer data? Tell me in the comments.
Top comments (0)