Create migration
Queues a store-to-store migration and returns its requestId.
You reference stores by BigCommerce store hash — never by token. Vortex IQ resolves each store’s API credentials server-side from your organisation’s connected StagingPro integrations, so tokens never travel through the browser or your code.
Pass a selection to migrate a subset rather than the whole store.
Guards enforced here
- Source and destination must be different stores.
conflict_strategy: replace(“Make Exact Copy”) is refused when the destination is a live production store, because it deletes destination-only items.- Selecting
orders,customers, orgift_certificatesrequiresanonymise_customer_data: true. - Every
theme_activationkey must appear inselection.themes, and a destination channel may be targeted by at most one theme activation. - Every
selection.page_template_globalsentry must appear inselection.page_templates.
auto_heal is accepted for compatibility but the platform always runs migrations with auto-heal enabled — it and the shared learning layer materially reduce failed migrations, so it is not operator-optional.selected_entities — the list of entity groups to copy from the
source store to the destination. This page explains everything that list controls: what you can
migrate, how entities depend on one another, how bulk differs from selective, and what happens when
you pass something the engine doesn’t recognise.
Bulk vs selective migration
A single request runs in one of two modes, decided entirely by whether you send aselection:
selection contains at least one non-empty array. An empty
selection: {} is treated as bulk.
Selective — Products tab, and so on), each sending exactly the payload the UI
sends: only that tab’s entity keys, that tab’s selection array, and conflict_strategy: "update"
(selective runs update existing destination items — that is the UI’s fixed behaviour). Selective
picks also scope entity counts and the
forecast, so a ten-product pick is sized as a
ten-product run.Supported entities
Entities fall into families. Each parent entity has a key you place inselected_entities; most
parents also own child entities that carry the detail beneath them. Every child key is itself a
valid selected_entities value — selecting a child alone forces its parent to run so the id-mapping
exists (see Dependencies).
Catalog — products, brands, categories
Catalog — products, brands, categories
optionsis not independently meaningful — variant options migrate automatically as part ofvariants. There is no options-only migration, so to move them, selectvariants.variant_metafieldsneedsvariants, andcomplex_rulesneedsmodifiers.- When both
categoriesandproductsare selected, product sort order (“featured” ordering within a category) migrates automatically — there is no separate key for it.
Customers & pricing
Customers & pricing
customers
parent — you must select customers (or customer_groups/customer_attributes) as well, or they
do nothing.Marketing offers & orders
Marketing offers & orders
order_status_{id} keys alongside orders — for
example ["orders", "order_status_11"]. With no status keys, all statuses migrate.Inventory
Inventory
Store settings
Store settings
Storefront settings
Storefront settings
Dependencies and automatic includes
Some entities can’t stand alone — the engine pulls in what they need so references resolve on the destination. Passing a wrong combination doesn’t error; the engine adds the prerequisites or drops the orphaned reference with a warning. Selecting a child forces its parent — but not the reverse. Selectingmetafields runs
products; brand_metafields runs brands; category_metafields runs categories; page_widgets
runs pages. The parent has to run so its source→destination id-map exists. The relationship is
one-way: selecting the parent (products) does not pull in its children — list each child key
you want (see the warning under Supported entities).
Selecting products auto-pulls the brands and categories they reference. On a selective product
run, the engine reads each picked product’s brand_id and category ids and migrates only those
brands and categories (plus category ancestors, so the tree is intact). A product’s custom
fields also travel automatically on a selective product run, even if custom_fields isn’t listed.
Hierarchies auto-include ancestors. Selective category picks pull in their parent categories;
selective page picks pull in their parent pages.
Some children need a sibling. variant_metafields needs variants (no variant id-map without
it); complex_rules needs modifiers (rules reference modifier values). If the sibling is absent,
that child is skipped with a note rather than failing the run.
Cross-entity references are remapped or dropped. Page widgets, promotions, and template
associations rewrite their entity ids through whichever id-maps the run built. A reference to
something not in the migration (for example a promotion targeting a category you didn’t migrate) is
dropped with a warning, because it would 404 on the destination.
Some storefront settings reference the catalogue. Two settings carry catalogue ids and so
depend on those entities migrating in the same run:
search_contextual_filters— BigCommerce contextual filters are configured per category (Contextual Filters), so each context’scategory_idis remapped through the category id-map. It needscategories.redirects— 301 redirects that point at a product, category, brand, or page are remapped through those id-maps. It needs the entities its redirects target.
Migration order
Entities always migrate in a fixed order so dependencies land first — you don’t control it, and the progress display’s order is cosmetic. Each step mirrors a real reference in the BigCommerce API, so an entity is never created before the ids it points at exist on the destination. The real order is:Theme, then brands, then categories
brand_id and a categories array, so
those ids must resolve first (Create a Product).Page widgets, then store and storefront settings
entity_id pointing at a specific product, brand, category, or page, so those ids must
be mapped first. Store and storefront settings follow for the same reason — the ones that carry
catalogue ids (per-category contextual filters,
and 301 redirects that point at a product/category/brand/page) can only remap those ids once the
catalogue has migrated.Content, inventory, customers, pricing
customer_group_id.Marketing offers, then orders
group_ids. Orders run last: their line items reference product_id and
the order carries a customer_id (Order Products).Business rules that affect selection
Customer data must be anonymised
Customer data must be anonymised
orders, customers, or gift_certificates requires anonymise_customer_data: true.
Without it the request is rejected:Conflict strategy decides how existing items are handled
Conflict strategy decides how existing items are handled
conflict_strategy controls what happens to an entity that already exists on the destination:skip(Add New Only, default) — leave existing items untouched.update(Update Existing) — additively update changed fields and child items.replace(Make Exact Copy) — update, then delete destination-only items so the destination mirrors the source.
replace is refused when the destination is a live production store, because it deletes data:replace still updates picked items but does not prune — a partial view
of the source can’t distinguish a genuine extra from an unpicked item.Source and destination must differ
Source and destination must differ
Storefront scope (multi-storefront)
Storefront scope (multi-storefront)
source_channel_id + destination_channel_id, the run maps one storefront to another. Set
channel_scoped_products: true to migrate only the products assigned to that source
storefront; otherwise all products migrate and are assigned to the mapped destination channel.Selective theme activation
Selective theme activation
selection.themes is present, the bulk activate_theme flag is ignored. Use
theme_activation to activate a picked theme on specific destination channels. Two rules are
enforced: every key must be a picked theme, and a destination channel may be activated by only
one theme (a channel has exactly one active theme). selection.page_template_globals must be a
subset of selection.page_templates.Invalid values and errors
Authorizations
A bearer token from Login, sent as Authorization: Bearer <token>. Valid for 10 days; scoped to the user and organisation it was issued for. Rotating or disabling the organisation's API credential immediately invalidates all outstanding tokens. Browser calls from a signed-in app.vortexiq.ai page are also accepted via session cookie — see Authentication.
Body
BigCommerce store hash to migrate from. Must be connected to your organisation.
BigCommerce store hash to migrate to. Must differ from the source.
Which entity groups to migrate — for example products, categories, brands, pages, page_templates, promotions, orders, customers. Child keys (e.g. variants, metafields, page_widgets) and settings keys are also valid and force their parent to run. Unknown keys are silently ignored, not rejected. See the full catalogue, dependencies, and rules above.
1full migrates; dry-run walks the migration without writing; verify compares only; counts totals only.
full, dry-run, verify, counts Required true when orders, customers, or gift_certificates are selected.
How an entity that already exists on the destination is handled:
skip— Add New Only (default): leave existing items untouched.update— Update Existing: additively update changed fields.replace— Make Exact Copy: update, then delete destination-only items. Refused against a production destination.
skip, update, replace Bulk theme migration: activate the migrated theme on the destination rather than only uploading it. Ignored when selection.themes is present — use theme_activation instead.
Accepted for compatibility only. Self-healing is always enabled.
Multi-storefront: the source storefront to migrate from. Pair with destination_channel_id.
x >= 1Multi-storefront: the destination storefront to map onto.
x >= 1Migrate only products assigned to source_channel_id. When false, all products migrate and are assigned to the mapped destination channel.
Explicit source channel id → destination channel id map, for mapping several storefronts at once.
Source storefront name, recorded for display in History.
Destination storefront name, recorded for display in History.
Selective migration picks. Parents and ancestors are included automatically, and products pull in their brands and categories.
Find the ids to pass here in the StagingPro app's Selective Migration tab. A selection also scopes entity counts and the forecast.
Selective themes only: which destination channels to activate each picked theme on, keyed by source theme uuid. Omit to upload the themes without activating them.
Every key must appear in selection.themes, and a destination channel may be targeted by at most one theme — a storefront channel has exactly one active theme.