Resource mappings
Each resource has a staging model — the flat, user-friendly shape your JSONata mapping should produce. Graftport then converts that shape into a Shopify-ready payload before pushing.
The point of staging models: you don’t have to learn Shopify’s full GraphQL input shapes. You return simple, flat JSON; Graftport handles the nested gymnastics.
Pages
| Resource | Staging model |
|---|---|
| Product | StagingProduct — title, price, variants, inventory, files. |
| Collection | StagingCollection — title, image, product list, menu metadata. |
| Customer | StagingCustomer — identity, single flat address, marketing consent. |
| Order | StagingOrder — flat addresses, flat discount fields, nested line items / transactions. |
| Discount code | StagingDiscountCode — single value (percentage / amount / free-shipping), flat min requirements. |
| Gift card | StagingGiftcard — code, value, recipient, debit history. |
| Blog & article | StagingBlog — one article + its blog reference. |
| Redirect | StagingRedirect — path + target. |
Shared fields
Every staging model inherits from a base. These fields are available on every resource — see Shared fields for the details.
original_id— the source’s stable ID (becomes a tracking metafield).source_url_path— original URL path (used by the redirect resource).exclude— boolean to skip this row entirely.dict_metafields— flat dict for any custom merchant data.metafield_prefix— namespace override fordict_metafields.
How to read each page
Each resource page has the same structure:
- Quick reference — the bare-minimum mapping that loads.
- Fields — every field grouped by purpose, with type, default, and a one-liner example per field.
- Patterns — fuller JSONata snippets for the common shaping problems.
- Gotchas — what trips people up the first time.
Extending the staging models
If you need a field that the staging model doesn’t expose:
- Custom merchant data — use
dict_metafields. That’s its job. - Source-platform-specific quirks — the staging model should cover the shape Shopify accepts; if a real merchant need is missing, contact the Graftport team to extend the model.
- A field Shopify doesn’t store — store it in
dict_metafieldsif it has post-migration value (audit, history); skip it otherwise.
Not yet supported
The following resource types have no staging model today, so JSONata output is passed through to the loader unchanged:
- Market — set up Shopify Markets manually after the migration.
- Article-only updates — articles are migrated as part of the blog resource; standalone article updates aren’t a separate resource.
Last updated on