Knowledge base
Shopify field mappings
A field mapping is the transformation between one Shopify field and the feed attribute it has to become. Almost none of them are a copy: barcodes need validating, descriptions need stripping, prices swap fields on sale, and several required attributes have no Shopify field at all.
| Shopify field | What has to happen in between |
|---|---|
| market.webPresence + priceList price, link | Selling into several markets means one feed per market, not one feed with several currencies. Each needs its own prices, its own currency, its own product URLs and its own tax treatment, and all four come from the market configuration rather than from the product. |
| product.body_html description | The Shopify description is rich text stored as HTML, and the feed description attribute wants plain text. The mapping has to strip the markup, decode the entities it leaves behind, collapse the whitespace that replaces the block elements, and only then truncate to the channel limit. |
| product.handle link | The product link is built from the store domain and the Shopify handle, with a variant parameter appended so each feed row lands on its own variant. The details that matter are which domain you use, whether the variant is preselected, and what happens when a handle changes. |
| product.id item_group_id | item_group_id is what tells a channel that several rows are variants of one product, and the Shopify product id is the natural source because every variant of a product shares it. The exception is a store whose variants are modelled as separate products, where the grouping has to come from somewhere else. |
| product.metafields / variant.metafields | Metafields are where the values a feed needs but Shopify has no field for actually live: gender, age group, material, net quantity, energy labels, style codes. They are also typed, namespaced and inconsistently populated, so reading one is more involved than reading a product field. |
| product.product_type google_product_category | Shopify product type is free text a merchant invents, while google_product_category must be a value from Google's own taxonomy. The mapping is therefore a lookup table from your vocabulary to Google's, not a field copy, and it decides which vertical requirements apply to each item. |
| product.status + publications | Deciding which products belong in a feed is a mapping in its own right, and it is not answered by status alone. A product can be active and unpublished, published and out of stock, or active with one variant that should never be advertised. |
| product.tags custom_label_0 | Custom labels are the five free-form fields a feed carries for your own segmentation, and Shopify tags are the obvious source. Because a product has many tags and a label holds one value, the mapping selects and derives rather than copies. |
| product.title title | The Shopify product title names the product, while the feed title has to name the specific variant, because each row is its own item. The mapping composes a title from the product name plus the attributes that distinguish the row, within the channel's character limit. |
| product.vendor brand | The Shopify vendor field is the obvious source for brand and the wrong one in most catalogues. It defaults to the store name, is used for suppliers and distributors as often as manufacturers, and is frequently inconsistent across a catalogue built over several years. |
| variant.barcode gtin, mpn, identifier_exists | The Shopify variant barcode field is where a GTIN lives, but Shopify neither requires nor validates it, so the mapping has to be conditional: use the barcode when it is a structurally valid GTIN, fall back to brand with mpn when it is not, and declare identifier_exists only for products that have none. |
| variant.compare_at_price price, sale_price | Shopify and the feed specifications disagree about which field holds which number. Shopify sells at price and shows compare_at_price struck through; a feed expects price to be the regular price and sale_price the reduced one, so on a discounted product the two fields swap. |
| variant.id id | The feed id must be unique per row, stable forever, and present on every item, which makes the Shopify variant id the safest source. A SKU is more readable but is neither guaranteed unique nor guaranteed to exist, and changing an id later costs the item its accumulated history. |
| variant.image / product.images image_link | image_link should be the variant's own image where one is assigned and the product's featured image otherwise, served at full size from the Shopify CDN. The mapping decisions that matter are which image each row gets, and not shrinking it on the way out. |
| variant.inventory_quantity + inventory_policy + inventory_management availability | Availability cannot be read from the Shopify inventory quantity alone. A variant with zero on hand is still purchasable when its inventory policy allows overselling, and a variant with inventory tracking switched off reports zero while being permanently available. |
| variant.option1 / option2 / option3 | Shopify stores variant options positionally as option1, option2 and option3 with whatever names the merchant typed, while feeds expect named attributes such as size and color. The mapping has to read the option by its name rather than its position, because the order differs from one product to the next. |
| variant.price price | The Shopify variant price is the amount a customer pays in the store currency, and the feed price has to match what the shopper will see on the landing page. What makes this non-trivial is tax treatment, currency formatting, and every discount mechanism that never touches this field. |
| variant.requires_shipping + product.is_gift_card availability | Gift cards, downloads, subscriptions and services are active, purchasable Shopify products that mostly do not belong in a shopping feed. The flags that identify them are the requires-shipping setting and gift card status, and neither is checked by a generator that maps fields rather than decisions. |
| variant.sku mpn | An mpn is the manufacturer's part number, and a SKU is your own stock reference, so the two coincide only when you are the manufacturer. Mapping SKU to mpn on resold goods sends a value no channel can match, which is worse than sending nothing. |
| variant.weight + weight_unit | The Shopify variant weight is the shipping weight of the packaged item, and it maps to shipping_weight with its unit attached. It is not the product's net weight, which matters because unit pricing needs the net contents and taking the shipping weight for it is wrong on every product. |
Frequently asked questions
Why can I not just export my Shopify catalogue as a feed?
Because a feed is a translation rather than an export. Shopify stores descriptions as HTML, prices under different names from the feed specification, and nothing at all for gender or age group, so every mapping does some work.
Which Shopify field mappings cause the most problems?
The barcode to gtin chain, because Shopify never validates it, and compare_at_price to sale_price, because the obvious mapping silently loses every discount in the catalogue.
What do I do about attributes Shopify has no field for?
They come from a metafield, from a tag or collection rule, or from a static value set once for the store. Gender, age group, material, net quantity and seller name are all in this group.