The mapping editor

Open a mapping from the migration’s Mappings tab or directly via /mappings/<id>. The editor has two panes:

Pane	What it does
Editor	Edit the JSONata expression with syntax highlighting and click-to-insert source fields.
Right pane	Inspect a sample source row and the live evaluated output for it.

The right pane has five tabs:

Tab	What it shows
Source	The picked sample row’s fields, searchable, click-to-insert into the editor.
Preview	A resource-aware rendered view of the Shopify result — labelled fields, images, variants, metafields, etc. This is what a non-technical reviewer can read without learning JSON.
Output	The raw `JSON.stringify` of the JSONata evaluation — handy for debugging the expression itself.
Fields	Every destination field you can map for this resource, marked mapped or unmapped so you can see what’s still available to fill in.
Lookups	Cross-resource lookups: pull a value from another resource (for example, a gift card’s owning customer via its order) and use it in the mapping as `$._refs.<name>`. See Cross-resource lookups.

Both tabs update automatically as you edit the expression. They differ in what they evaluate:

Output runs the JSONata in-browser and prints the raw result.
Preview sends the source row + expression to the worker, which evaluates the JSONata server-side, runs it through the same staging conversion the transform phase uses (convert_staging), and renders the resulting Shopify-shape payload — so source-side fields like original_id, input_variants, sku, price appear as they would after staging (folded into metafields, variants, etc.) rather than raw passthrough.

Seeing what’s left to map

A template only fills in the fields it was built for, so it’s easy to miss fields you could be migrating. The Fields tab lists every destination field for the resource and marks each one mapped or unmapped, with a count of how many you’ve covered. Toggle Unmapped only to focus on the gaps, search by name, and click an unmapped field to drop it into the expression ready to fill in.

Some fields are filled in for you from what you’ve already mapped (for example product variants and SEO). These appear in a separate Computed group and are read-only — you don’t map them directly.

Saving a change

Saving creates a new mapping version. The migration’s mapping automatically advances to the new version — past versions stay inspectable in the version history but no migration references them unless you re-pin one deliberately.

Saving a mapping does not re-run anything. Records that were already staged keep their old payloads until the next transform run touches them.

Forking a default template

You can’t edit a default template directly. Clicking Fork on a migration’s mapping does three things:

Copies the current default template’s version into a new tenant-owned template.
Repoints this migration’s mapping at the fork.
Leaves other migrations untouched — they stay on the default.

After forking, edits save into your fork’s version history.

Dry-running without mutating

To see the effect of a change on real data without writing a new version: use the Sample input pane with a real source row. It runs the expression in-browser and shows the output. No version is created, nothing downstream changes.

This is the loop you want while iterating:

Extract (or reuse recent extract data).
Paste a row into Sample input.
Tweak the expression until the preview looks right.
Save — new version, migration auto-advances.
Run a transform-only pass and inspect the staged records.
Run load when you’re happy.

Diffing versions

Every mapping’s page lists its version history. Click two versions to see a side-by-side diff of the JSONata. Useful when you’re unsure what changed between the run that worked and the run that didn’t.