curl --request POST \
  --url https://app.vortexiq.ai/v2/api/bc-migration/migrations \
  --header 'Content-Type: application/json' \
  --cookie vortexiq_session= \
  --data '
{
  "source_store_hash": "abc123xyz",
  "destination_store_hash": "def456uvw",
  "selected_entities": [
    "products",
    "categories",
    "brands"
  ],
  "mode": "full",
  "conflict_strategy": "skip"
}
'

{
  "requestId": "5A3C1B2E-7F4D-4E6A-9B8C-0D1E2F3A4B5C",
  "status": "queued",
  "mode": "full",
  "forecast": {
    "products": 1200,
    "variants": 5400,
    "brands": 40,
    "categories": 210,
    "memMB": 2048,
    "cpus": 2,
    "etaSeconds": 5400,
    "tier": "medium",
    "basis": "forecast",
    "at": "2026-07-16T09:00:00.000Z"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123,
  "errors": {}
}

{
  "message": "Store Migration is not enabled for this organization."
}

{
  "error": "replace_not_allowed_on_production",
  "message": "'Make Exact Copy' can't be used here: the destination you selected is a live production store, and this option deletes anything that exists only on the destination. Please choose 'Add New Only' or 'Update Existing', or pick a staging (non-production) destination store."
}

{
  "error": "proxy_failed",
  "message": "migration service unreachable"
}

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, or gift_certificates requires anonymise_customer_data: true.
Every theme_activation key must appear in selection.themes, and a destination channel may be targeted by at most one theme activation.
Every selection.page_template_globals entry must appear in selection.page_templates.

Self-healing is always on. 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.

POST

migrations

curl --request POST \
  --url https://app.vortexiq.ai/v2/api/bc-migration/migrations \
  --header 'Content-Type: application/json' \
  --cookie vortexiq_session= \
  --data '
{
  "source_store_hash": "abc123xyz",
  "destination_store_hash": "def456uvw",
  "selected_entities": [
    "products",
    "categories",
    "brands"
  ],
  "mode": "full",
  "conflict_strategy": "skip"
}
'

{
  "requestId": "5A3C1B2E-7F4D-4E6A-9B8C-0D1E2F3A4B5C",
  "status": "queued",
  "mode": "full",
  "forecast": {
    "products": 1200,
    "variants": 5400,
    "brands": 40,
    "categories": 210,
    "memMB": 2048,
    "cpus": 2,
    "etaSeconds": 5400,
    "tier": "medium",
    "basis": "forecast",
    "at": "2026-07-16T09:00:00.000Z"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123,
  "errors": {}
}

{
  "message": "Store Migration is not enabled for this organization."
}

{
  "error": "replace_not_allowed_on_production",
  "message": "'Make Exact Copy' can't be used here: the destination you selected is a live production store, and this option deletes anything that exists only on the destination. Please choose 'Add New Only' or 'Update Existing', or pick a staging (non-production) destination store."
}

{
  "error": "proxy_failed",
  "message": "migration service unreachable"
}

Authorizations

vortexiq_session

string

required

Your signed-in Vortex IQ session (browser calls). Requests are scoped to your organisation, which must have Store Migration enabled. For server-to-server calls use a bearer token instead — see Authentication.

Body

application/json

source_store_hash

string

required

BigCommerce store hash to migrate from. Must be connected to your organisation.

destination_store_hash

string

required

BigCommerce store hash to migrate to. Must differ from the source.

selected_entities

string[]

required

Which entity groups to migrate, for example products, categories, brands, pages, promotions, themes, page_templates, orders, customers.

Minimum array length: 1

mode

enum<string>

default:full

full migrates; dry-run walks the migration without writing; verify compares only; counts totals only.

Available options:

full,

dry-run,

verify,

counts

anonymise_customer_data

boolean

default:false

Required true when orders, customers, or gift_certificates are selected.

conflict_strategy

enum<string>

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.

Available options:

skip,

update,

replace

activate_theme

boolean

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.

auto_heal

boolean

Accepted for compatibility only. Self-healing is always enabled.

source_channel_id

integer

Multi-storefront: the source storefront to migrate from. Pair with destination_channel_id.

Required range: x >= 1

destination_channel_id

integer

Multi-storefront: the destination storefront to map onto.

Required range: x >= 1

channel_scoped_products

boolean

Migrate only products assigned to source_channel_id. When false, all products migrate and are assigned to the mapped destination channel.

channel_map

object

Explicit source channel id → destination channel id map, for mapping several storefronts at once.

Show child attributes

source_storefront

string

Source storefront name, recorded for display in History.

destination_storefront

string

Destination storefront name, recorded for display in History.

selection

object

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.

Show child attributes

theme_activation

object

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.

Show child attributes

Example:

{
  "3f2b8c14-9d5e-4a71-b0c6-2e8f7a1d4b93": [1, 2]
}

Response

Migration queued.

requestId

string

Identifies the run. Use it with every other migration endpoint.

status

enum<string>

Available options:

queued

mode

enum<string>

Available options:

full,

dry-run,

verify,

counts

forecast

object | null

Sizing forecast computed at kickoff, when available.

Show child attributes

Get forecast

List migrations

Get Started

The AI OS

Create migration

Authorizations

Body

Response