How Gatemi Store Migration Works

Three rules govern the plugin, in both editions. Each one prevents a real failure of migration tools.

  1. The silence rule. Nobody is emailed while a migration runs.
  2. One row, one record. Running the same file twice changes nothing.
  3. The resume rule. A migration is a cursor in the file, not one long request.

The full edition adds a fourth, for orders: the money rule — an imported order keeps the totals it was exported with.

The flow

  1. You upload a CSV and press Start. A job is saved (option gmsm_job in the full edition, gmsmf_job in the free edition) holding the file's path, the source, the kind of record, a byte offset of 0 and the counts.
  2. While the job is open, a cron event runs every minute (gmsm_run / gmsmf_run, on a one-minute schedule the plugin adds only while it is needed).
  3. Each run reads the next 50 rows from where the last stopped, imports them, and updates the counts.
  4. At the end of the file the job is marked finished, the cron event is removed, and the screen shows the report.
  5. Done — clear this and start another removes the job (and, by default, the file).

1. The silence rule

A migration creates records in bulk, and WooCommerce treats every new order and every new account as something to email about. Left alone, an order import sends every customer in the file their receipt again — years of them — which cannot be undone and is how a shop's sending domain lands on a blocklist on the day it moves platform.

So while a job is open (from init, priority 1, and again before a Run the next batch now press), the plugin switches off:

  • WooCommerce's emails — new order, processing, completed, on hold, refunded, cancelled, failed, invoice and new account — through their woocommerce_email_enabled_* filters;
  • WordPress' password-change, email-change and new-user notification emails;
  • Full edition: the new-customer notification flag, and stock reduction for orders (woocommerce_can_reduce_order_stock), because those orders were fulfilled in another shop and your stock levels are what is on the shelf today.

Nothing is silenced when no migration is open, so an ordinary order placed the minute after a migration finishes behaves exactly as it always did.

Full edition: imported orders are also created directly at their final status rather than moved into it, so WooCommerce's status-change emails have nothing to fire on.

2. One row, one record

Every record the plugin writes carries a source id in the meta key _gmsm_source — for example shopify:the-blue-kettle — and that id, not the SKU or the title, decides whether a row updates an existing record or creates a new one. Real exports have duplicate SKUs and duplicate titles; keying on them doubles a catalogue on the second run.

Record Source id On a second run
Product source + the product's handle (Shopify) or ID (WooCommerce), lower-cased Updated
Customer source + the email address, lower-cased Updated — an existing account is never replaced
Order — Full edition source + the order number Left exactly as it is
Coupon — Full edition source + the code, lower-cased Updated

Why orders are the opposite: a product is a description of something for sale, and should follow your corrected file. An order is a record of something that happened; it may have been edited, refunded or annotated since, and a second run must not undo that.

Customers are matched by email address. If an account with that address already exists on the site, it is updated — billing first name, last name, email, phone, city and country, each only when the file has a value — and its password, role and order history are left alone. A new account gets the customer role, the email as its username and a random password; the customer sets their own with Lost your password?.

A row the plugin cannot identify is skipped and counted, never guessed at — a product with no handle, a customer with no valid email, an order with no number, a coupon with no code. Importing it would create a fresh copy every time the file is read.

Nothing is ever deleted. A migration only creates and updates.

Because both editions write the same _gmsm_source mark and keep their settings in the same gmsm_settings option, a shop can import its products and customers with the free edition and then its orders with the full edition without ending up with two of anything.

3. The resume rule

A shop with twenty thousand products cannot be imported inside one web request. The job keeps a byte offset into the file. Each run seeks to it, reads a batch, and saves the new offset before importing the batch. A run that dies mid-batch therefore loses at most one batch — and since every write is keyed on the source id, re-reading that batch changes nothing anyway.

The offset is bytes, not a row number, because finding row 14,000 by counting means reading 13,999 rows again on every batch. The header row is read once, on the first batch, and kept on the job.

If the uploaded file disappears before the job finishes (a host clean-up, a deploy), the job is finished with the reason "The uploaded file could not be read." rather than left running every minute for ever.

Reading the rows

  • Headers are matched ignoring case and surrounding spaces, and each field has a list of candidate headers, because exports from the same platform differ by locale, app and year. See Accepted CSV columns.
  • A row with fewer cells than headers is padded with empty cells, not refused — exporters routinely drop trailing empty columns.
  • Money is read the way spreadsheets write it. When both , and . appear, the rightmost is the decimal point, so 1.250,00 is 1250. With only a comma, three digits after it is a thousands separator (1,250 is
    1. and anything else is a decimal (12,50 is 12.5). Currency symbols are ignored.
  • Products: a row with no title of its own is a Shopify variant line under the product above it, and is skipped. A sale price is set only when it is above zero and below the regular price — Shopify's "Compare at" column holds the old price, and setting it would show every product as discounted from itself. A stock figure turns stock management on; an empty one leaves it alone. Categories are split into paths on commas and pipes — never on spaces — and > makes the next name a child of the one before it. A WooCommerce row whose Type is variation is skipped.
  • Published: true, yes, 1, publish, published, active or visible count as published. Anything else — including an empty cell — is a draft. A product is published only when the file says so and Publish imported products straight away is on.

The money rule — Full edition

An imported order is a record, not a sale. Its totals are written exactly as exported — shipping, tax and the order total — and WooCommerce is never asked to recalculate them from today's prices and tax rates. An order that recalculated would move your historical revenue every time you edited a price.

Each order row becomes one line item: the line's name, quantity and price from the file, with the line subtotal and total both set to price × quantity (leaving the subtotal unset would make every imported line look fully discounted). When the row has a SKU that matches a product in the store, the line is linked to that product — which is why products should be imported first.

The order's billing email is set, and the order is attached to the customer account with that email if one exists. The currency and the creation date come from the file.

Status: the exported status is mapped to a WooCommerce one.

Exported WooCommerce
refunded, partially_refunded Refunded
cancelled, canceled, voided Cancelled
unfulfilled, partial, processing, pending Processing
anything else, including empty Completed

Unknown reads as completed rather than pending: these orders already happened, and a pending order is one WooCommerce's own housekeeping cancels.

Coupons — Full edition

A coupon is created with its code (lower-cased), its amount and a type. A type containing percent or % becomes a percentage discount; anything else becomes a fixed cart discount. No other restrictions are imported.

The report

Every row ends up in exactly one count: created, updated or skipped. Their sum is the number of data rows in the file. Skipped rows are grouped by reason, in the merchant's terms — "No email address, so there is no account to make." — so the report tells you what to fix. A finished job is kept until you clear it, so the report is still there next week.

Shopping Cart
Scroll to Top