How Gatemi Order Import Works

Most people run an importer twice. The first time they are not sure it worked, so they run it again. An importer that creates a second copy of everything on that second run leaves a shop with duplicate coupons, doubled revenue in every report, and an afternoon of deleting by hand.

Gatemi Order Import is built around four rules that stop that from happening. The coupon rules are the same in both editions. The order rules are the full edition's.

Rule 1: running the same file twice never imports it twice

Every record has an identity the file carries:

  • A coupon is its code. Before a row is written the importer asks WooCommerce whether a coupon with that code exists (wc_get_coupon_id_by_code()), after formatting the code the way WooCommerce does — so SPRING10 and spring10 are the same coupon.
  • An order is your reference — Full edition. The reference column holds your own id for the order: the number it had in your old shop, your marketplace order id, anything that is unique to it. The importer stores it on the order as _gmoi_ref and looks it up there on every run.

If the identity is already in the shop, the row updates that record. If it is not, the row creates one. A second run of the same file therefore updates everything the first run created and creates nothing.

Two things follow:

  1. A file with no identity column is refused whole. A coupon file with no code column, or an order file with no reference column, imports nothing and says why. Importing it "hopefully" would create everything again on the next run.
  2. The same identity twice in one file is a mistake in the file. For coupons, the first row with a code is used and later rows with that code are skipped and reported. For orders, see Rule 5.

The Let an import update … that already exist setting decides whether the update happens. Switched off, an existing code or reference is skipped and reported instead — still never created twice.

Rule 2: the dry run is the importer

A dry run is not a separate "validate" routine. It is the same code path with the last step — writing — taken away. It reads the file, matches the headers, checks each discount type against the shop's discount types, checks each order status against the shop's statuses, looks up each product by SKU or id, and decides create, update or skip. Then it writes nothing.

That matters because a separate preview drifts from the real thing the first time somebody fixes one and not the other. Here a dry run and a real run of the same file report the same problems, because they are the same decisions.

Rule 3: every problem names the line it is on

The report at the top of the screen has three parts:

  1. The summary. "120 rows read — 112 created, 6 updated, 2 skipped." Created, updated and skipped are counted apart, so you can tell that a file re-ran rather than reading "120 imported" and wondering.
  2. Columns that were not recognised. Any header that is not one of the plugin's columns is named, and that column is left alone. It is never guessed at — a column called Price is not quietly read as amount.
  3. Rows that need attention. A table of every problem with the line in your file it is on: "Line 213: No product matches "MUG-B", so that line was left off the order."

The line number counts the header as line 1. A cell that contains line breaks inside quotes counts once, so on such a file the number can be a little lower than your editor's line number. The table shows at most 200 problems; a file with the wrong header would otherwise list one per row.

Rule 4: an order's money is what the file said — Full edition

An imported order is history. It was placed at last year's prices, maybe in a currency the shop no longer sells in, with a shipping rate it no longer offers. So:

  • order_total is set on the order exactly as written.
  • shipping_total is set exactly as written.
  • A product line with an item_total gets that amount as both its subtotal and its total. A line with no item_total is worth what WooCommerce prices it at when it is added.
  • WooCommerce's calculate_totals() is never called.

If a new order has no order_total in the file, its total stays at zero. Give every order a total.

Rule 5: one order is several rows, kept together — Full edition

An order with three products is three rows sharing one reference. The order's own fields — status, date, addresses, totals — are read from the first row of the group. Each row that carries an item_sku or item_id adds one product line. A row with no product at all is simply the order's own row.

The rows for one reference must be next to each other. The importer finishes an order the moment the reference changes. If the same reference turns up again further down, those rows are skipped and reported: "The rows for "A-1042" are not together in the file; this one was skipped. Sort the file by reference and run it again."

What an update changes

Coupons: only the columns the file carries. A file with just code and usage_limit changes the usage limit of each coupon and nothing else. An empty date_expires cell means "no expiry" and clears it; leaving the column out leaves the expiry alone.

Orders — Full edition: the order's fields follow the same rule, with one difference: an empty cell is ignored rather than clearing the field. When the file has an item_sku or item_id column, the product lines are replaced on an update — every existing line is removed and the lines in the file are added. A file is your statement of what the order is; adding to the existing lines would double them on every run. A file with no item column says nothing about the lines and leaves them as they are, so a file that only corrects postcodes does not touch them.

The flow of one order row — Full edition

  1. The row's reference is read. A row with none is skipped.
  2. If it is a new reference, the previous order is finished (step 6).
  3. On the first row of a group: the status is checked — a wc- prefix is removed, and a status the shop does not have is reported and dropped, leaving the order in WooCommerce's default status.
  4. Each product is found by item_id, or by item_sku when there is no id. A product that cannot be found is reported and its line left off. Quantity is at least 1.
  5. The order is looked up by _gmoi_ref.
  6. When the group ends: create or update, set the reference first, set the fields, replace the lines, set the shipping total and the order total, set the status, and save.

Setting a status such as processing or completed is a normal WooCommerce status change. WooCommerce may send its usual customer emails and reduce stock for it, exactly as if a shop manager had changed it. Run a small file on a staging copy first.

Exporting coupons

Download coupons.csv writes every coupon — published, draft, pending and private — in exactly the coupon columns the importer reads, so an export imported into another shop recreates the same coupons. The file starts with a byte-order mark so Excel on Windows shows accented characters correctly. A cell that begins with =, +, - or @ is written with a leading ', so a spreadsheet does not run it as a formula. Coupons are read 200 at a time.

The full edition imports orders but does not export them; for that, see Gatemi Order Export.

Shopping Cart
Scroll to Top