Product mapping

Product name customers see. Used to construct the URL handle if you don’t set one explicitly.

"title": name

URL slug. Letters, hyphens, numbers only. Auto-derived from title if omitted.

"handle": $lowercase(url_key)

Brand or supplier name. Indexed for storefront filters.

"vendor": manufacturer

One of ACTIVE, ARCHIVED, DRAFT. Defaults to DRAFT so migrated products don’t accidentally go live mid-migration.

"status": status = "enabled" ? "ACTIVE" : "DRAFT"

Product description with HTML markup (<strong>, <em>, lists, etc.). Plain text works too.

"descriptionHtml": description

Searchable tags. The staging model deduplicates and sorts before emitting to Shopify (so ["red", "RED", "red"] becomes ["RED", "red"]).

"product_tags": $append(categories, ["migrated"])

Sort position within collections. Lower = earlier.

The price customers pay. Always a string, even if your source has it as a number — wrap with $string().

"price": $string(price)

The “compare-at” / strikethrough price for showing a discount. String, like price.

"compareAtPrice": rrp > 0 ? $string(rrp) : null

Unit cost (what the merchant pays for the product). Used for margin reporting in Shopify, not shown to customers.

"cost": $string(cost_per_unit)

Whether the product is taxable.

Tax classification code. Use only if the merchant has a custom tax service that requires specific codes.

Optional list of price entries for multi-currency or per-market pricing. Each entry shape depends on the merchant’s market setup.

The Shopify location GID where this product’s inventory is held. Get it from your migration’s location config (run Resync locations on the migration if it’s not populated yet).

"location_id": $$.config.default_location_gid

For multi-location merchants, pick the location based on the source row.

Available quantity at location_id.

"inventoryQuantity": qty_in_stock

What happens when stock hits zero:

• DENY — block customers from ordering.
• CONTINUE — allow ordering anyway (oversell).

"inventoryPolicy": allow_backorder ? "CONTINUE" : "DENY"

Low-stock threshold for the merchant’s internal alerts. Doesn’t affect Shopify’s own low-stock notifications.

Minimum purchase quantity. Stored as a metafield, not a hard constraint — surface this in the theme if the merchant cares.

Stock keeping unit. Should be unique per shop. On a product without variants, this is the variant SKU.

"sku": sku

UPC, EAN, GTIN, ISBN — whichever the merchant uses.

Product weight in the merchant’s chosen unit (set on the shop, not per product).

"weight": weight_kg

Supplier’s internal product number. Stored as a metafield.

Set true if this product is a gift card SKU (rather than a gift card balance — for that, use the gift card resource).

Array of nested product shapes — each describes one variant. The nested shapes use the same fields as the parent (price, sku, inventoryQuantity, optionValues, etc.).

If input_variants is empty, Graftport auto-creates one variant from the parent product itself with the synthetic option Title = Default Title.

"input_variants": children.{
  "original_id": child_id,
  "sku": sku,
  "price": $string(price),
  "inventoryQuantity": qty,
  "location_id": $$.config.default_location_gid,
  "options": [
    { "optionName": "Size",  "name": size  },
    { "optionName": "Color", "name": color }
  ]
}

Variant-level options as an explicit list of { optionName, name } pairs. Used inside input_variants to declare which option values that variant has.

"options": [
  { "optionName": "Size", "name": size }
]

Alternative way to declare options on a variant: up to three pairs of option_name_N + option_value_N. Equivalent to options but flatter — sometimes easier when the source already has columns like color, size, length.

{
  "option_name_1": "Color", "option_value_1": color,
  "option_name_2": "Size",  "option_value_2": size
}

Pick one form per variant — don’t mix options and option_name_N. Mixing is allowed (they’re concatenated) but harder to reason about.

The parent product’s external ID. Set on variants (entries inside input_variants) so Graftport knows which product they belong to. The parent’s original_id is the natural value.

Variant-scoped metafields. Same shape as dict_metafields, but only set on variants — the parent’s dict_metafields describe the product itself.

"variant_metafields": {
  "warehouse_bin": bin_location
}

Array of images attached to the product (not a specific variant). Each entry needs at minimum originalSource (the URL Shopify will download from).

"files": gallery.{
  "originalSource": "https://cdn.example.com/" & path,
  "alt": label,
  "contentType": "IMAGE"
}

contentType is one of IMAGE, VIDEO, MODEL_3D. Defaults to IMAGE.

Graftport auto-matches files to variants by checking if the option value (e.g. "red") appears in the file URL — variants that match get the file assigned automatically. So if your file URLs follow product-red.jpg, product-blue.jpg, etc., the right image lands on the right variant.

A single file attached to a variant. Set this inside an input_variants entry to pin one specific image to one variant.

"input_variants": children.{
  "sku": sku,
  "file": {
    "originalSource": image_url,
    "contentType": "IMAGE"
  }
}

If you set the parent’s files and let Graftport’s filename matching kick in, you usually don’t need to set per-variant file manually.

The <title> tag on the product page. Defaults to the product title if omitted.

"meta_title": seo.title

The meta description shown in search results.

"meta_description": seo.description

Array of source-platform collection IDs (or Shopify GIDs) this product belongs to in manual collections. Graftport resolves source IDs to Shopify GIDs at load time using the collection migration’s results.

"collections": category_ids