Trial to BYOK migration

When a trial user subscribes, StoreFrame does not transform the trial environment in place. A fresh production environment is provisioned on the customer's own BYOK cloud account, the trial's Magento data is synced into it, and the trial is destroyed. From that point forward, every environment in the organization runs under BYOK.

Mechanically this is the same as cloning a production environment into a Stage — a new VM with the same containerized stack, then Magento state copied across. The only differences: where the two environments live, and that the trial source is destroyed at the end.

Prerequisites

Before the migration can begin the customer needs:

• An active trial environment in trial_active state (see provisioning lifecycle)
• Cloud provider API credentials registered at Settings → Organization → Providers (see cloud providers)
• A valid payment method, supplied through Stripe Checkout during the Subscribe flow

The migration flow

The migration runs as a single background job triggered when Stripe confirms the subscription payment. It executes in four phases.

1. New environment provision (BYOK) — StoreFrame calls the customer's provider API with the registered token and provisions a new VM on their account, running the same containerized Magento stack as the trial. The new environment enters provisioning and progresses identically to a fresh BYOK provision; see watching a provision run for the live status page.

2. Data sync from trial → new environment — once the new environment passes healthchecks, the trial's Magento data is synced across (database, media, configuration). This is the same sync primitive used to seed Stage environments from production.

3. Trial environment teardown — after the sync succeeds, the trial transitions to destroyed and its infrastructure (on StoreFrame-owned hardware) is torn down. There is no cleanup required on the customer's cloud account — the trial never ran there.

4. Slot activation — the new environment transitions to active, the Project slot starts billing, and the subscription is reconciled with Stripe before the transition is committed (see provisioning lifecycle § Slot accounting).

Failure handling

If the new provision or the data sync fails, the trial stays active and its countdown continues — the trial timer is not paused. The customer can retry from the project page. The Stripe charge is held until the migration completes; if the customer gives up before the trial expires, the held charge is refunded automatically.

Related pages

• Trials — full trial lifecycle and subscription touchpoints
• BYOK vs BYOC — what changes between the trial period and the paid environment
• Provisioning lifecycle — state machine and slot accounting
• Cloud providers — registering BYOK credentials before subscribing

Note: the underlying data sync primitive (used by both Stage seeding and trial → BYOK migration) does not yet have its own dedicated page. The flow above is grounded in trials § "Subscribing during the trial" and provisioning lifecycle § "Convert trial to production". A dedicated environment-clone procedure doc is the next logical addition.