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 three 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 post-staging Shopify payload — 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.

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.

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.