Documentation

1. Overview

Shop Shift is an embedded Shopify app that copies data from a WooCommerce store into a Shopify store. It reads WooCommerce through its REST API v3 and writes to Shopify through the Admin GraphQL API.

Three design rules shape everything else:

• Nothing runs in your browser. A migration is a set of background jobs on our servers. The page only reports on it.
• Everything is chunked. WooCommerce is read a page at a time and Shopify is written a batch at a time, so store size does not change how it behaves.
• Every record is mapped. We remember which WooCommerce record became which Shopify record, which is what makes a re-run safe.

2. Requirements

3. Getting started

Step 1 — Create WooCommerce API keys

In WordPress admin go to WooCommerce → Settings → Advanced → REST API → Add key:

• Description — anything, e.g. "Shop Shift"
• User — an administrator account
• Permissions — Read is enough; Shop Shift never writes to WooCommerce

Copy the consumer key (ck_…) and secret (cs_…) — WooCommerce shows the secret only once.

Step 2 — Connect the store

In Shop Shift open WooCommerce, paste the store URL, key and secret, then press Test connection. On success you will see your WooCommerce and WordPress versions. Your credentials are encrypted before they are stored and are only ever shown back masked.

Step 3 — Start a migration

Migrations → New migration. Pick what to migrate; the wizard shows how many records exist in WooCommerce and how many your plan covers. Anything your plan does not include is disabled with the reason shown.

Optional settings on this screen:

• Weight unit — WooCommerce does not report its unit through the API, so pick the one your store uses. Product weights are imported with it.
• Custom tags — added to every migrated product and customer, handy for finding or rolling back a batch later.
• Default vendor — used for products with no brand. Leave blank to let Shopify default it to your shop name.
• Email me when this finishes — a summary email when the run completes.

Step 4 — Let it run

Press start and close the tab if you like. Progress updates every few seconds while you watch, and the Activity log shows what is happening in real time.

4. What gets migrated

5. Field mapping reference

Products

Customers

Phone numbers are the most common source of customer rejections. WooCommerce stores whatever the shopper typed ("0300 1234567"); Shopify requires international format. Shop Shift uses the billing country to add the correct calling code and strip the national trunk prefix. If a number still cannot be made valid it is left out and the customer is migrated without it.

Orders

Orders are created with their original date, inventory is bypassed so historical orders do not move your stock, and no receipts are sent to customers.

6. What is not migrated

• Customer passwords — WooCommerce and Shopify hash passwords in incompatible ways. This is not a limitation we can remove; your customers set a new password on first login.
• Themes and design, menus, and standalone WordPress pages.
• Gift cards and subscriptions.
• Review ratings as Shopify's own review system — Shopify does not have one. The review data itself is migrated onto each product; see section 4.
• Refund records attached to orders (the order's status is migrated, the individual refund transactions are not).
• SEO redirects from old WooCommerce URLs.
• Anything in WooCommerce plugins that is not exposed through the REST API.

7. How the migration engine works

Starting a migration creates a plan and then walks it:

Start
  ├─ count each selected entity in WooCommerce
  ├─ cap each total to your plan limit
  ├─ create batch rows (one per page of source data)
  └─ dispatch the first batch

Batch  (repeats until none are left)
  ├─ fetch one page from WooCommerce
  ├─ migrate each item into Shopify
  ├─ checkpoint after every item
  ├─ stop after ~35 seconds and continue in a fresh job
  └─ hand over to the next batch

Finalize
  ├─ recompute the final counters
  ├─ set the overall status
  └─ send the completion email if requested

Three properties make a run hard to break:

• Resumable. Progress is checkpointed after every single record, so a worker that dies mid-page resumes at the next record rather than replaying the page.
• Time-bounded. No job runs long enough to be considered dead and restarted underneath itself.
• Self-advancing. Each batch hands over to the next when it ends — successfully or not. One broken batch costs that batch, never the migration.

A watchdog sweeps for runs that have stopped making progress for any reason outside the app and resumes them automatically.

Dependency order

Entities always run in an order that satisfies their dependencies: categories → products (so products can join their collections) and customers → orders (so orders can be associated by email).

8. Re-running and idempotency

Every migrated record is written to a mapping table keyed by (shop, entity type, WooCommerce ID). Before creating anything, Shop Shift looks the record up.

The practical result: running the same migration twice never gives you two of anything.

9. Error handling and field shedding

Real WooCommerce stores contain data Shopify refuses. Rather than failing the whole record, Shop Shift removes the offending optional field and tries again, up to three rounds — so several bad fields are shed one after another. The record lands, and a warning tells you exactly what was left out.

If a rejection touches something required, or an error set mixes an optional problem with a real one, the record still fails — loudly and with the reason — so genuine problems never hide behind a partial success.

There is one shortcut worth knowing: if several products in a row have their images rejected, Shop Shift concludes the store's media is unreachable, logs a warning, and stops sending images for the rest of that run. This roughly halves the work on a store whose uploads folder is gone.

Rate limits

Shopify throttling is expected, not exceptional. When it happens the batch is re-queued for after the throttle window and resumes exactly where it stopped. Nothing is lost and nothing is duplicated.

How fast a migration is allowed to run is derived from your store’s real Shopify API budget, which the app reads from Shopify’s own responses rather than assuming. A store on a larger Shopify plan is given a larger budget, so it is migrated faster.

Why orders are slower than products

Shopify limits order creation separately from the ordinary API budget, and that limit is small. It is also the only limit Shopify does not publish a number for — it is reported as an ordinary error with no timing attached. So orders carry their own ceiling on how many can be created at once, on top of everything else:

Because Shopify does not publish the order limit, these figures are a starting point rather than a promise. If Shopify refuses at that rate, the migration backs off automatically, waits and tries again — settling at whatever your store actually allows. That is why an order migration can take considerably longer than a product migration of the same size, and why more servers or more workers do not speed it up: the limit is on Shopify’s side, per store.

Everything else — products, collections, customers, coupons and content — is paced against your WooCommerce store instead, because those are the phases that read heavily from it: a single product means reading its variations and image details as well. So they run considerably wider than orders, but they are limited by what your WordPress host can serve rather than by anything on the Shopify side.

10. Plans and limits

Limits are enforced in three places so they cannot be worked around by accident:

• The wizard disables entities your plan does not include and shows how many of your records it covers.
• The API refuses to create a migration for an entity outside your plan.
• The engine caps every batch to the remaining allowance.

Upgrading takes effect immediately — start a new migration and the higher limit applies.

11. Progress, logs and notifications

• Per-entity progress — processed / total, successful and failed counts, updated about once a second while a run is active.
• Activity log — a live feed of what the run is doing, including plan-limit warnings, skipped fields and per-record errors.
• Downloadable report — a plain-text summary of the run, every failed item with its reason, and the full log. This is the single most useful thing to attach when contacting support.
• Completion email — optional, requested in the wizard.

Counters are derived from the mapping table rather than incremented as work happens, so the numbers you see are always the truth even if a batch was replayed.

12. Retrying failed items

A finished migration with failures shows every failed record with the exact message Shopify returned. Retry failed items re-fetches just those records from WooCommerce and re-migrates them — it does not re-run the whole migration.

Records that no longer exist in WooCommerce are marked skipped rather than retried forever. Fix the underlying problem first — that is usually a plan upgrade, a reachable image URL, or a corrected customer email — then retry.

13. API reference

The app's API is consumed by its own embedded frontend and authenticated with a Shopify session token. It is documented here for reference and for debugging; it is not a public integration API, and it is not versioned.

Migration status shape

{
  "id": 102,
  "status": "processing",
  "entities": [
    { "type": "product",  "total": 1250, "processed": 840,
      "successful": 820, "failed": 20, "percentage": 67.2 },
    { "type": "category", "total": 35,   "processed": 35,
      "successful": 35,  "failed": 0,  "percentage": 100 }
  ],
  "started_at": "2026-08-08T10:30:00Z",
  "completed_at": null
}

Statuses are pending, processing, completed, completed_with_errors, failed, cancelled and paused.

14. Security model

• Credentials encrypted at rest. WooCommerce keys and Shopify tokens are encrypted in the database and only ever returned masked.
• Short-lived Shopify tokens. Offline access tokens expire and are refreshed automatically.
• HMAC verification. Every OAuth callback and webhook is verified before it is trusted.
• Session-token auth. Every API call from the embedded app carries a signed Shopify session token, validated on each request.
• Tenant isolation. Every query is scoped to a single shop.
• Read-only at the source. Shop Shift never writes to or deletes from your WooCommerce store.

See the privacy policy for what is stored and for how long.

15. Troubleshooting

If none of these fit, download the migration report and send it to support. It contains everything we need.

16. Glossary