DataDock Handbook

How a run works

Every import goes through two separate phases, and there is a human decision between them. This is the whole design of the app: phase one writes nothing at all.

1. Point DataDock at a file

   Upload it, paste a share link, pull it off an FTP server, or let a schedule fetch it. A zip becomes one job per file inside; a Google Sheet becomes one job per tab.

2. It parses and resolves

   Every row is matched against what is already in your store. Ragged rows, blank columns, duplicate headers and unknown columns all become warnings — never a rejected file.

3. You read the diff

   A per-row plan in your own column names, with counts of what would be created, updated and deleted. Nothing has been written to Shopify yet.

4. You approve — then it applies

   Only now does DataDock touch your store. Under ~1,000 records it uses plain GraphQL; above that it switches to bulk operations.

5. Rollback stays available

   Before each mutation an inverse patch is written to a journal. One click replays them in reverse.

Installing

Install DataDock from the Shopify App Store, or open the install link you were given. Shopify shows you the access scopes first — read them; DataDock asks for exactly the scopes its sixteen data types need and nothing more.

After install the app lives in your admin sidebar under Apps → DataDock, with its own sub-navigation: Home, Import, Export, Jobs, Schedules, Servers, Plan and Settings.

Home opens on Recent activity — the last jobs, their state, and anything that needs your attention. A fresh install shows an empty state; that is normal.

Order history older than 60 days

Shopify caps order exports at 60 days unless an app is granted read_all_orders, and that grant is only given after a listing review. If you need full order history, ask support to have it enabled for your store; until then, order exports stop at the 60-day boundary and say so.

Your first run, in five minutes

Do not start by writing a spreadsheet from scratch. Start by exporting what you already have — that gives you the exact column names DataDock expects, filled with real data.

1. Export a small slice

   Go to Export, choose Products, and run it. You get an XLSX with one row per variant and every column the app understands.

2. Change one thing

   Open the file, pick a handful of rows, and edit a single column — Variant Price is a good first test. Save it. Do not delete the columns you did not touch; blank cells are safe.

3. Import it back

   Import → Upload, pick the file. The job appears in Jobs and moves to Preview ready.

4. Read the preview

   Open the job. You should see exactly the rows you edited, and No change on everything else. If you see thousands of unexpected changes, stop and read How cells are read before approving.

5. Approve, then roll back

   Apply it, confirm the prices changed in your admin, then hit Roll back on the same job. Watch them return. Now you know what the safety net actually does.

Where your file can come from

The file does not have to live on your computer. DataDock can go and get it, which is what makes supplier feeds and recurring work possible.

Which file types are accepted, and exactly how each one is read, is its own section: File formats & samples.

Moving from WooCommerce, Magento or BigCommerce

Upload the product export exactly as your old platform wrote it — no reshaping. DataDock recognises it by its columns and turns it into up to three jobs, each with its own preview: Products (variants, prices, stock, images, SEO), Collections (one per category, filled by tag) and Redirects (old product links to the new pages). Everything it changed or left out is listed at the top of each preview.

Both settings are on the Import page under Moving from WooCommerce, Magento or BigCommerce?. Apply Products first; Collections and Redirects can follow in any order. Products with more than 3 options, bundles, grouped products and translations are left out and named in the preview.

File formats & sample files

DataDock reads Excel workbooks, CSV, TSV and zip archives, and writes Excel or CSV. Anything else is refused up front with the list of types it does take — never half-read.

Not supported: the old Excel format .xls, .numbers, .ods and JSON. Save as .xlsx or CSV first.

Size limits

Your plan also caps how many records one file may hold — see Plans & caps.

How a file is read

• The header row is the first row that is not blank. Blank rows above it are skipped with a warning.
• Header names are forgiving about case, spacing and punctuation: Body (HTML), body html and Body HTML are the same column. Anything it still cannot place goes to Columns we don't know.
• One row per child record. Products take one row per variant, collections one per rule, customers one per address. Repeat the Handle; leave product-level cells blank on the extra rows.
• Ragged rows — a row with more or fewer cells than the header — are a warning, not a rejected file. So are blank rows and blank columns.
• A leading apostrophe ('00123), which spreadsheets use to keep a SKU, barcode or phone number as text, is dropped rather than imported as part of the value.
• Encoding: save CSVs as UTF-8 (Excel: CSV UTF-8). The byte-order mark Excel adds is handled. Other encodings turn accented letters into garbage — the preview shows it before anything is written.
• Exports from other apps work as they are. Shopify's own product CSV is recognised column for column; Matrixify-style sheets are too, including their truncation banner, which is read as end-of-data with a warning.

Which data type a file is

For an Excel workbook, the tab name decides: a tab called Products, Collections, Redirects and so on is imported as that type, and tabs with other names are skipped and listed. Inside a zip, the file name does the same job (Collections.csv). Otherwise the Data type you chose on the Import screen is used — and if the columns clearly belong to another type, the job page says so and offers to re-read it.

Sample files

Every sample uses made-up products whose handles start with dd-test-, so nothing collides with your catalogue, and none contains customer data. Import them on a development store, read the preview, and use products-delete-test.csv to clean up.

How cells are read

This is the single most important page in this handbook. Read it before your first real import.

In DataDock, a blank cell means “leave this alone”. It does not mean “set this field to empty”. Clearing a value is always something you ask for explicitly.

The three rules

• Blank cell → nothing happens. The field is not sent to Shopify at all.
• A value → that value is set, if it differs from what is stored.
• The literal text <CLEAR> → the field is emptied. This is the only way a blank result happens by accident-proof design.

Telling a row what to do: the Command column

Every row carries an instruction. By default it is MERGE — update what matches, create what does not — and you set that default on the Import screen under Default command. It is deliberately the forgiving one.

When rows need to behave differently from one another, add a Command column to the sheet and put one of these in it. A blank cell, or no Command column at all, falls back to the default you picked.

Comparison is type-aware

The preview would be useless if re-importing an export showed thousands of phantom changes, so values are compared by meaning rather than by text:

Metafields

Metafield columns are written as Metafield: namespace.key — for example Metafield: custom.care_instructions. They are resolved when the file is parsed, because no two stores have the same metafields. Real exports also write a type suffix, like Metafield: custom.related [list.product_reference]; that is read and understood, though your store's own definition always wins, since that is the one Shopify validates against.

Translations

The Translations sheet has one row per field (Title, Body HTML, SEO Title…) and one Translation Value: fr column per language. It is the layout Matrixify uses, so its translation files import as they are. Export it first: you get every field in every language your store has, with the Original Value beside it, and Translation Is Outdated marks the ones whose original has changed since. In the export filter, name what to translate (Collection, Page, Blog Post, Shop…); leave it blank for products.

A row finds its record by Entity ID, or by Entity Handle for products, collections, pages and blogs, so a file from another store works too. A blank cell leaves a translation alone and <CLEAR> removes it. A language must already be added in Shopify under Settings → Languages. Rollback puts every translation back as it was, and removes the ones the import added.

Columns we don't know

A supplier's file will not use your column names. When DataDock meets a header it cannot place, it does not reject the file and it does not guess.

The job page gets a Columns we don't know panel: each unrecognised header, the reason it could not be placed, and a dropdown to say what it means. You answer once.

1. Map each column

   Pick the field it corresponds to, or mark it as ignored.

2. Re-check

   The preview is rebuilt from the same file with your mapping applied. Still nothing has been written.

3. It is remembered

   The mapping is saved per shop and per data type, so the next file in that format maps itself.

AI help

DataDock uses AI in two small places, and only where the ordinary rules have already given up. It never writes to your store, never decides anything on its own, and is included on every plan.

What is sent, and what is not

• It only suggests. A wrong guess costs you one dropdown; nothing is mapped or applied until you confirm it and approve the preview.
• When unsure, it says nothing. It is told to leave a column blank rather than guess, because a wrong mapping would quietly corrupt data.
• If it is unavailable, nothing breaks. The mapping panel and error list work exactly as they do without it.
• Mappings you confirm are remembered per data type on Growth and above, so the same supplier file maps itself next time without asking the AI again.

Try it with products-supplier-columns.csv, whose headers are in German and Spanish.

Reading the preview

The preview is the product. It is worth knowing how to read it properly.

The tally

At the top: how many records would be created, updated, deleted and left alone. Check this number against what you expected before you read a single row. A price update that reports creations means identity columns are not matching — usually a handle or SKU column that got renamed.

The rows

Each changed row shows the column, the stored value and the new one, in your headers: Variant Price: 10.00 → 12.50. Rows with nothing to do are marked No change and can be filtered out.

Warnings

Blank columns, blank rows, ragged rows and duplicate headers produce warnings and keep going. Read them — a duplicate header usually means two columns are fighting over one field.

Rows that can never apply

The planner refuses a row Shopify's API could not accept, and says why, instead of failing halfway through the run. Orders are the common case: Shopify only permits edits to email, note, tags and metafields on an existing order, so a file that changes an order's line items will report those rows as impossible rather than applying some of them.

Applying, and rolling back

Approving the preview starts phase two. DataDock picks its write strategy by size on its own: below roughly 1,000 records plain GraphQL is faster, above it bulk operations win.

How rollback works

Before every single mutation, DataDock writes an inverse patch to a journal:

• An update stores the record's prior snapshot.
• A create stores a delete.
• A delete stores the whole record.

Rolling back replays those patches in reverse order. It is not a re-import of an older file — it is the exact inverse of what was actually done, row by row.

Images

Shopify fetches image URLs itself, after reporting the mutation as successful — which is how a dead link silently produces a product with no image and a job that says “ok”. DataDock checks every URL before sending it: an unreachable one is dropped, named on the row, and the rest of the record still applies. Re-importing an unchanged export sends no images at all, so it costs nothing.

Exporting

Open Export, choose a data type, and run it. Exports stream from Shopify straight to disk, so catalogue size is not a constraint — and unlike imports, exports are never capped on rows.

Narrowing it down

The filter box takes Shopify's own search syntax — status:active vendor:Acme, and so on. The filter is applied by Shopify rather than after the fact, so a narrowed export is genuinely faster, not merely smaller. Leave it empty to export everything.

Choosing columns

The Columns panel lets you search and tick exactly the columns you want. Select none and you get every column, which is what you want when the export is going to be edited and re-imported — a column that is not in the file cannot be round-tripped.

Format

Excel (.xlsx) is the default and the better choice for anything you intend to edit and re-import. CSV is there for feeding other systems.

Getting the file

• Download it from the job page.
• Share a link. Results are handed out through a signed, time-limited URL that works outside the Shopify admin — so an export can be sent to a supplier or pulled by a build script without giving anyone admin access.
• Deliver it somewhere. Send the finished file to a saved FTP/SFTP server automatically.

An export is the best starting point for an import

Because the exporter and the diff planner render records through the same code, an exported sheet is by definition in the exact shape the importer expects. Editing an export is always safer than authoring a file from scratch.

Edit in the app

For a few changes, skip the spreadsheet. Edit in the app opens your records as a table: pick the data type, which records (the same search as the filter box) and the columns to change, then click a cell and type. Changed cells turn yellow and show what they were. A finished export opens the same way from its job page.

• Review changes writes nothing. It sends every record you touched — a product with all its variants, an order with all its lines — as an UPDATE import, so you get the usual preview, approve it, and can roll it back.
• Change many rows at once: tick rows (or the box at the top for every row shown), pick a column and set a value, raise or lower a number by a percentage, or add or remove tags. A record's own fields, such as a product's Title, change once per record; a variant's fields on every row.
• IDs and the column records are grouped by (such as Handle) are locked, so an edit can never land on the wrong record. Emptying a cell clears that value.
• One table shows up to 2,000 rows; narrow the records to reach the rest.

Catalog health

Catalog health reads your products and lists what needs fixing. Press Check my products: a few seconds for most stores, a few minutes for a large catalogue, and you can leave the page meanwhile. The check itself changes nothing, and every plan can run it.

• A fix works like any other edit in the app: Review changes sends it as an UPDATE import, so you see the preview, approve it, and can roll it back. Your plan's record limit applies to the fix, not to the check.
• The results show your products as they were when the check ran. Press Check again after fixing to see what is left.
• Archived products are left out. One check reads up to 20,000 products.
• A check is not listed under Jobs & history and has no file to download. Use Export for that.

Schedules

A schedule repeats an import or export on a plain interval. Under Schedules → New schedule you give it a source, a data type and how often to run.

Each run fetches the file fresh — a supplier who overwrites the same path every night is the normal case. And each run still builds a preview that a human approves.

Schedules require the Growth plan or above.

Saved servers

Under Servers you can save an FTP, FTPS or SFTP connection once and then use it in both directions — pull a supplier's file for an import, or have an export delivered to it.

How credentials are held

• Encrypted at rest with AES-256-GCM.
• Never returned to the browser. Once saved, a password cannot be read back out of the app — only replaced.
• Each server is scoped to your shop alone.

Saved servers require the Growth plan or above.

What you can import and export

Seventeen sheets, 293 columns. The C / U / D columns show what Shopify's API actually permits — not what DataDock wishes it could do. The planner refuses a row it could never apply rather than failing partway through a run.

Metafield columns are available on every sheet above, as dynamic Metafield: namespace.key headers, on every plan including Demo.

Plans and caps

Three plans. Demo is free forever, so you can try every feature on real data before you pay. Growth and Agency have no free trial.

One Agency plan, ten stores

Shopify bills every store on its own invoice, so the Agency plan is paid on one store, and that store covers up to nine more. On the paying store, Plan & billing › Your agency stores shows a link code. Install DataDock on another store, open Plan & billing there and enter the code under Covered by an agency? — that store is on Agency straight away, with no charge of its own.

• The paying store can remove a store, and a linked store can leave, at any time. A new code stops the old one; stores already linked stay linked.
• If the paying store cancels, downgrades or uninstalls, its linked stores go back to Demo until it pays for Agency again.
• A store that already pays for its own plan cannot be linked: downgrade it to Demo first, so it is never charged twice.

How the caps actually count

• Per file, not per month. There is no monthly quota to run out of mid-migration.
• Records, not rows. A product with twenty variants is one product, not twenty.
• Checked before anything is written. A file over the cap is refused up front, naming the count and the limit — an import never stops halfway through.

Growth's other per-file limits: 300 collections, 1,000 orders, 1,000 draft orders, 5,000 inventory rows, 300 discounts, 50 companies, 50 pages, 50 blogs, 50 blog posts, 50 metaobjects, 10,000 redirects, 366 payout rows, and unlimited menus.

When something goes wrong