> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# StagingPro V2 Migration API

> REST API reference for the StagingPro V2 BC Migration app - browse a store, forecast a migration, launch it, and follow it live.

<Note>
  This reference covers the StagingPro **V2** Migration API. For the classic StagingPro REST API,
  see the [apimatic tutorial](https://stagingpro.apimatic.dev/#/rest/step-by-step-tutorial).
</Note>

Everything the [StagingPro](/vortex-apps/staging-pro/index) 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.

```
https://app.vortexiq.ai/v2/api/bc-migration
```

Calls are authenticated as your Vortex IQ user and scoped to your organisation - either with a
**bearer token** from the [Login](/vortex-apps/staging-pro/api/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](/vortex-apps/staging-pro/api/authentication).

## How it is organised

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/vortex-apps/staging-pro/api/login">
    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.
  </Card>

  <Card title="Counts & Forecast" icon="calculator" href="/vortex-apps/staging-pro/api/get-forecast">
    Size a migration before you run it - exact entity totals, plus an ETA and capacity estimate.
    Neither endpoint creates a run.
  </Card>

  <Card title="Migrations" icon="rocket" href="/vortex-apps/staging-pro/api/create-migration">
    Launch bulk or selective migrations, list history, read run detail, inspect per-item issues, and
    stream live progress.
  </Card>

  <Card title="Controls" icon="pause" href="/vortex-apps/staging-pro/api/pause-migration">
    Pause, resume, cancel, and verify. Resume continues from a checkpoint rather than starting over.
  </Card>
</CardGroup>

## A typical flow

<Steps>
  <Step title="Know your stores">
    [Log in](/vortex-apps/staging-pro/api/login) 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Launch">
    `POST /migrations` with a source hash, a destination hash, the entities to migrate, and a
    conflict strategy. You get back a `requestId`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify">
    `POST /migrations/{id}/verify` re-runs the same scope read-only and compares source against
    destination without writing anything.
  </Step>
</Steps>

## 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](/vortex-apps/staging-pro/api/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

| Mode      | What it does                                                 |
| --------- | ------------------------------------------------------------ |
| `full`    | Migrates the selected entities. The default.                 |
| `dry-run` | Walks the full migration without writing to the destination. |
| `verify`  | Read-only comparison of source against destination.          |
| `counts`  | Entity totals only.                                          |

## Conflict strategy

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

| Strategy  | UI name         | Behaviour                                                                           |
| --------- | --------------- | ----------------------------------------------------------------------------------- |
| `skip`    | Add New Only    | Leaves existing destination items untouched. The default.                           |
| `update`  | Update Existing | Additively updates changed fields on matched items.                                 |
| `replace` | Make Exact Copy | Updates, then deletes destination-only items so the destination mirrors the source. |

## 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](/vortex-apps/staging-pro/api/authentication).