Before you start

1. Activate Commerce (Settings → Plugins).
2. Configure a payment provider under Settings → Connections if you will take new orders in Birkly after cutover.
3. Optionally activate User Management if buyers will get accounts later (invite / password-reset only — Shopify passwords are never imported).
4. Back up content/ and data/ before a production import.
5. Freeze Shopify catalog edits for the window you are transferring so dry-run counts match import.

Steps 1–3 (solid)

1. Prep / connect

1. In Shopify Admin, create a custom app (Admin API) with read access to products, customers, and orders.
2. Copy the Admin API access token and shop domain (your-store.myshopify.com).
3. In Birkly: Commerce → Settings → Import & migrate.
4. On the Shopify beta card under Live store sync, save shop domain, access token, target collection, and default currency. Cutover reuses these credentials.
5. Open the Shopify cutover panel above the live sync cards.
6. Click 1. Test connection and confirm the API responds.

Do not treat this as a standing two-way sync. Credentials are for transfer (and optional later Beta product sync), not for Birkly writing back to Shopify.

2. Map the content model

Decide how Shopify objects become Birkly content before you import.

Shopify	Birkly
Product	Parent CMS entry in the target collection (Commerce field)
Variants	Variant sub-entries (same pattern as CSV / live product import)
Images	First image URL mapped onto the product row (media ingest when configured)
Customer	Commerce Customers profile (source: shopify, email as unique key)
Order (history)	Commerce order with status: archived and source: shopify_archive

Passwords are never imported. Existing Shopify login credentials do not move. If you use User Management, invite customers or send password-reset links after go-live.

Pick a target collection that already has the Commerce fieldtype (or create one during import setup). Align SKUs and parent/variant relationships with how you want Catalog and Inventory to read after import — see Commerce warehouse stock for stock modes.

3. Dry-run product import

1. In Shopify cutover, set Resources to Products only for the first pass (or All when you are ready for a combined run).
2. Click 2. Dry-run. Review product counts and sample titles/SKUs. No catalog entries are written.
3. When samples look right, click 3. Import cutover and confirm. Import requires a dry-run token or an explicit confirm.
4. Continue with Customers only, then Archived orders only, or run All once you trust the mapping.

After products land, open Catalog (and CMS entries) to spot-check prices, SKUs, variants, and images before you import history.

Customers and archived orders (same panel)

Use the same Resources selector and dry-run → import flow:

• Customers only — upserts Commerce customer profiles by email; tags and Shopify customer id are retained when present; no passwords.
• Archived orders only — writes historical orders tagged as Shopify archive. Idempotent on Shopify order id (re-import skips existing).

Archived orders do not re-fulfill. They skip payment capture, inventory decrement/reservation, PostPurchaseRouter fulfillment, and paid Automation emails. Treat them as read-only commercial history for support and reporting.

Rollback

If a batch looks wrong:

1. Click Rollback last batch in the Shopify cutover panel (enabled after a successful import), or
2. Call the admin API action shopify_cutover_rollback with the batch_id from the import result.

Rollback removes customers and archived orders created by that cutover batch and rolls back the linked product import when recorded. Prefer rollback over hand-deleting mixed catalog rows.

Steps 4–11 (checklist outline)

These steps complete a full merchant move. Steps 4–5 are available in the cutover panel today; 6–11 are the remaining go-live checklist. Cutover itself does not import gift-card balances, discount rules, tax class mappings, or open fulfillments — recreate those in Commerce after products/customers land (see promotions, tax, gift cards, fulfillment).

Step	Checklist
4. Customers	Dry-run → import customers; verify profiles under Commerce Customers; plan invite / password-reset (no password migration).
5. Orders archive	Dry-run → import archived orders; confirm status archived, no stock movement, no fulfillment emails; spot-check totals and line items.
6. Verify catalog + inventory	Rebuild catalog index if needed; set Inventory mode (Unlimited / Simple / Locations); reconcile on-hand vs Shopify before go-live.
7. Memberships / purchase options	Map Shopify subscriptions or memberships to Commerce purchase_options and Settings → Mappings; test one recurring or membership SKU if used.
8. Storefront / checkout smoke	Rebuild storefront on Birkly (commerce-storefront.js / templates — not Liquid); test ship, deliver, register, and membership paths you sell.
9. Gift cards / credits	Recreate or migrate balances only when your Commerce version supports it; disable Shopify gift-card codes at cutover so they are not double-spent. (Balance import is not claimed as shipped with cutover alone.)
10. Discounts + DNS cutover	Recreate critical discount codes in Commerce; put Shopify in password / closed mode; point domain to Birkly; smoke-test checkout on the live host.
11. SEO + hypercare	Publish redirects CSV (old Shopify URLs → Birkly); reconcile inventory daily for the first week; disable Shopify apps that still charge fees; keep Shopify admin read-only as needed.