Skip to main content
This reference covers the StagingPro V2 Migration API. For the classic StagingPro REST API, see the apimatic tutorial.
Everything the StagingPro BC Migration app does - browsing a store’s catalogue, sizing a migration, running it, controlling it, and streaming its progress - is available over REST, so you can drive migrations from your own tooling instead of the UI.
Calls are authenticated as your Vortex IQ user and scoped to your organisation - either with a bearer token from the Login endpoint (scripts, CI, backend services) or your signed-in session (browser). Stores are referenced by store hash; BigCommerce tokens are resolved server-side and never sent by you. See Authentication.

​
How it is organised

Authentication

Exchange your identity and your organisation’s API credential for a bearer token. The login response also lists your organisation’s connected stores and their hashes.

Counts & Forecast

Size a migration before you run it - exact entity totals, plus an ETA and capacity estimate. Neither endpoint creates a run.

Migrations

Launch bulk or selective migrations, list history, read run detail, inspect per-item issues, and stream live progress.

Controls

Pause, resume, cancel, and verify. Resume continues from a checkpoint rather than starting over.

​
A typical flow

1

Know your stores

Log in to get a bearer token. The response lists every store your organisation has connected in StagingPro, with the store hash you will use as source and destination on the endpoints below.
2

Size it before you commit

POST /forecast returns an ETA and capacity tier for exactly the scope you intend to run - including your picks and conflict strategy. POST /entity-counts gives exact totals.
3

Launch

POST /migrations with a source hash, a destination hash, the entities to migrate, and a conflict strategy. You get back a requestId.
4

Follow it

Subscribe to GET /migrations/{id}/stream for live Server-Sent Events, or poll GET /migrations/{id}. GET /migrations/{id}/issues itemises anything that failed or was intentionally skipped, with reasons.
5

Verify

POST /migrations/{id}/verify re-runs the same scope read-only and compares source against destination without writing anything.

​
Bulk or selective

A migration moves either the whole scope of the entities you select, or just the items you pick. For a selective run, find the item ids in the StagingPro app’s Selective Migration tab, then pass them as selection on Create migration. Picks cover products, categories, pages, promotions, plus theme uuids and page-template files. Picked themes can be activated per destination channel with theme_activation. A selection also scopes counts and forecasting, so a ten-product pick is estimated as a ten-product run rather than a whole-store one.

​
Modes

​
Conflict strategy

How an entity that already exists on the destination is handled:

​
Safety

The API enforces the same staging-first guardrails as the UI:
  • replace is refused against a production destination. It deletes destination-only items, so it may never target a live store - the server rejects it even if a client asks.
  • A store can never migrate onto itself.
  • Customer data must be anonymised. Selecting orders, customers, or gift_certificates requires anonymise_customer_data: true.
  • Stores are authorised per organisation. You can only read or migrate stores your organisation has connected.
  • Runs are resumable and auditable. Every run checkpoints as it works; pause, resume, and cancel are first-class, and the issue log records every failed or skipped item with a reason.
  • Self-healing is always on. Migrations run with auto-heal enabled; it is not optional.
Start with Authentication.