Mappings

A mapping is the function that turns one source row into one Shopify-shaped record. It’s expressed in JSONata — a JSON query and transformation language.

Templates, mappings, versions

Three layers, each doing a specific job:

Layer	What it is	Who owns it
Mapping template	A named recipe scoped to a source platform + resource type — e.g. Magento → Products v1.	Default templates are global (read-only). Forks belong to your tenant.
Mapping	A specific migration’s resource pinned to a specific template version. There’s one per `(migration, resource)`.	Your tenant.
Mapping version	An immutable snapshot of the JSONata text. Every save creates a new version.	Whoever owns the template.

Pinning a migration to a specific mapping version means that version defines forever what that migration’s transforms produce — you upgrade when you choose to, not by accident.

When to fork

Use the default template as long as it works. Fork when the merchant needs:

A custom attribute mapped (e.g. lager_position → an inventory location).
A different image base URL.
A localized option value the default template doesn’t normalize.
Anything else the default doesn’t cover.

Forks are tenant-private. Other tenants can’t see them.

Reading a mapping

A mapping is JSONata that takes the source row as input and returns the destination payload. A trimmed example:


{
  "title": name,
  "handle": $lowercase(url_key),
  "vendor": manufacturer ? manufacturer : "Unknown",
  "variants": variants[].{
    "sku": sku,
    "price": $string(price),
    "inventoryQuantity": qty
  }
}

The output is what gets staged for the load phase. Graftport then pushes that payload to Shopify using the right Admin API call for the resource.

See Mappings → JSONata basics for the patterns that come up most.