Mappings

Mappings are where most of the configuration work in a real migration happens. The default templates cover the common case; merchant-specific quirks need a fork.

This section covers:

• JSONata basics — the language. Skim if you’ve used JSONPath or jq before.
• Templates & versions — the three-layer model and why it exists.
• The mapping editor — what the in-app editor does.
• Forking a template — when, why, and how.

When to leave mappings alone

If the merchant’s data is shaped like a normal Magento or Shopify store and they don’t have unusual integrations, the default templates will do the right thing. Run an extract + transform, look at the staged payloads, and only fork if you see something wrong.

A common mistake is forking too early — every fork is a maintenance liability when the upstream template improves.