Surfaced

Shopify Catalog Mapping: Send Metafield Data to AI Channels

Published

Last checked against Shopify's Help Center: October 18, 2026.

If your store keeps its best product data somewhere other than the standard product fields (a "short title" metafield, a long description in a metaobject, separate products for each color), AI shopping channels may be seeing a weaker version of your catalog than your customers do. Shopify's Catalog mapping tool exists for exactly this case. This guide covers what it changes, when it's worth using, and how to set it up step by step.

What Shopify Catalog mapping does

Shopify Catalog is the structured feed Shopify builds from your products for Shop and agentic storefronts, the channels that put your products in AI assistants such as ChatGPT, Microsoft Copilot and Google's Gemini. Shopify says Catalog consolidates variants and groups identical items, and the Shopify Catalog mapping tool lets you optionally customize that data in three areas:

  • Product fields: choose the source Catalog uses for each product's title, description and category.
  • Compare-at: choose whether compare-at prices are sent to AI agents.
  • Custom combined listings and options: group separate products that are really variants of one product, and set option display names.

Two things make this low-risk to try:

  1. It only changes what reaches Shopify Catalog. Shopify says mapping changes don't affect your store's own product structure or your online store data. Its optimization guide puts it the same way: mapping changes how products display in Catalog "without affecting the key product data that you have in your online store."
  2. Defaults are already set. Shopify bases the default options on an analysis of your store's product data, so you're adjusting, not starting from scratch.

One thing to plan around: Shopify says changes are processed with a delay, so don't expect to see them in AI channels the minute you save.

Do you need it? A quick test

Shopify says customization is most useful for stores that use metafields, metaobjects, tag prefixes or title delimiters. In practice, mapping is worth 15 minutes if any of these sound like your store:

  • Your real description lives in a metafield. Some themes and page builders store the full description in a custom field and leave the standard description short or empty. AI platforms consider the description when matching products to questions (Optimizing your products), so a near-empty standard description is a real gap.
  • Your titles are written for your theme, not for a stranger. If the standard title is a collection name ("The Voyager 2") and a metafield holds a descriptive one ("Men's Waterproof Hiking Boot"), mapping lets you send the descriptive one to Catalog.
  • You sell each color or size as a separate product. Common with large catalogs and imports. Without grouping, each one can appear as its own listing.
  • You run sales with compare-at prices and want (or don't want) agents to show strikethrough pricing.

If none of these apply and your standard title, description and product category are already complete, the defaults are probably fine. Spend the time on filling in product categories instead.

Step 1: Point title, description and category at the right source

From Shopify's mapping instructions:

  1. In your Shopify admin, go to Sales channels > Agentic.
  2. In Sources, expand Shopify Catalog and click Review product data mapping.
  3. In Product fields, change the Source for the title, description or category. Sources can be product attributes, product metafields or metaobject references.
  4. If products are missing a required field, click the message and use Bulk edit products to fill them in.
  5. Optionally, check the result in the Preview tab.
  6. Click Save.

Things to know before you pick a source:

  • One source per field. You can't combine a metafield with the standard description, so pick the source that's most complete across your catalog, then fill the gaps there.
  • Empty sources stay empty. If you map the description to a metafield that only half your products have filled in, check the products flagged as missing the field before saving.
  • The Preview isn't a guarantee. Shopify says the Preview tab is not an exact indicator of how AI channels display your data. Use it to catch obvious mistakes (wrong field, HTML fragments, truncated text), not to predict ranking.

Category deserves a careful look. Shopify classifies products from your product information, and products it classifies as uncategorized are excluded from Catalog (Catalog requirements). If your categories are stored somewhere other than the standard product category field, mapping the category source correctly matters. If they aren't stored anywhere, set the standard Shopify product category first. Shopify's metafields guide explains that category metafields are product attributes tied to a specific category (for a shirt: size, neckline, color), so a correct category also unlocks the right attribute fields.

Step 2: Decide on compare-at prices

The Compare-at switch on the same mapping page controls whether compare-at prices go to AI agents (mapping page):

  • On: Catalog sends a compare-at price only when it's higher than the current price, and agents may show it as strikethrough pricing.
  • Off: only the current price is sent.

Your store starts with a default, and Shopify notes that the default doesn't change automatically if you later change how you use compare-at prices. So if you've stopped running permanent "was/now" pricing, or started, revisit this switch. For developers: Shopify says eligible compare-at prices are sent in the list_price field of the Universal Commerce Protocol (UCP) Variant specification.

A practical rule: turn it on only if your compare-at prices are real, current reference prices. Leftover compare-at values from an old sale on some products are a reason to clean up the data first.

Step 3: Group products that are really variants

If you sell "Linen Shirt - Blue" and "Linen Shirt - White" as two products, Custom combined listings can present them to Catalog as one product with a color option. From the mapping page:

  1. On the same Review product data mapping screen, turn on Custom combined listings.
  2. Accept or reject any suggestions Shopify shows, or choose a Combination method:
    • Product title: pick the Delimiter that separates the shared name from the variant part. By default there are no spaces around it; if your titles use spaces (as in "Linen Shirt - Blue"), choose Other and enter the delimiter with its spaces.
    • Product metafield: pick a Combination metafield. Supported types are single line text, product reference list, metaobject reference and metaobject list.
    • Product tag: enter a prefix in Tag starts with (for example, a tag like group-linen-shirt on every product in the group).
  3. Optionally, under Options, click Add options, pick an option and confirm or edit its Display name.
  4. Check the Grouping tab and review Additional products in group.
  5. Click Save.

The Grouping tab reports each product as:

  • Combined: grouped successfully.
  • Left separate: no shared value was found, so it stays its own listing.
  • Need review: two variants in the group have the same option combination. Fix these, or the group won't make sense to a shopper.

Limits and caveats Shopify lists:

  • Groups built from a title, a tag, or a metafield that doesn't hold product references can contain up to 10,000 products. Groups from a product-reference-list metafield can contain up to 1,024 products, with up to 100,000 across all groups. Oversized groups show an error before you save and aren't combined.
  • Unstructured metafields produce no preview in the Grouping tab.
  • Turning on Custom combined listings replaces your Shopify Combined Listings app setup for Catalog. If you're on Plus and already use the Combined Listings app (which Shopify says is available only on Plus and enterprise plans), check your existing groups before switching.

Which method to choose? If your titles follow one consistent pattern, the title delimiter is the quickest. If they don't, a tag prefix is the easiest to apply in bulk with the product bulk editor or a CSV. A product reference list metafield is the most explicit but takes the most setup.

Step 4: Verify, then leave it alone

After saving:

  1. Wait. Shopify processes mapping changes with a delay.
  2. Use the search preview in the Agentic section to run a few real customer questions and see which products come back. Shopify notes channels re-rank results, so treat it as directional (how to use the search preview).
  3. Check listing quality. The Agentic section scores description completeness, image coverage, variant and option completeness and policy completeness (Managing agentic storefronts). If description completeness was low because the text lived in a metafield, this is where you'd hope to see a change.
  4. Write down what you mapped. Mapping lives in the Agentic settings, not in your product data, so the next person who reorganizes your metafields should know Catalog depends on them.

Mistakes to avoid

  • Mapping to a metafield that's not maintained. If your team stops filling it in for new products, new products go to AI channels with an empty field.
  • Sending marketing copy as the title. AI platforms consider the title when matching products to questions. A title that doesn't say what the product is ("Our bestseller!") doesn't help.
  • Grouping products that aren't variants. A bundle and its single items, or two different products that share a word in the title, don't belong in one group. Review the Need review and Combined results, not only the errors.
  • Assuming mapping fixes eligibility. Mapping changes how eligible products are described. It doesn't override the Catalog requirements: a product with a $0 price, no image, an Unlisted status or an excluded category still won't be included.

Where Surfaced fits

Mapping only works if the source fields are filled in. Our free AI readiness checker gives a quick read on your storefront, and if you want to fix gaps in bulk, our app, Surfaced, finds products with missing categories, alt text and barcodes and applies fixes you can undo. Disclosure: we make it. Catalog mapping itself is a Shopify setting, and everything above can be done without any app.

Checklist

  • Open Sales channels > Agentic > Sources > Shopify Catalog > Review product data mapping
  • Title, description and category each point to the most complete source in your catalog
  • Products flagged as missing a required field are filled in
  • Compare-at switch matches how you actually price today
  • Separate color/size products are grouped, with clear option display names
  • No groups left in Need review
  • After processing, checked the search preview and listing quality

Sources