Catalog operators running Shopify stores often store carefully written bullet points in product metafields—compatibility notes, key features, care instructions—but those values never reach the shopping feed unless you explicitly map them. This article walks through how to retrieve a metafield value from the Shopify Admin GraphQL API and write it into the product_highlight attribute that Google Merchant Center accepts.
What Google Requires for product_highlight
Before pulling any data from Shopify, it helps to understand what the destination attribute actually expects so you don't map the wrong type of content.
According to Google documentation, product_highlight is a repeated field. Each highlight is a string of 1–150 characters. Google requires a minimum of 2 highlights and allows a maximum of 100, with 4–6 recommended per product. Because it is a repeated field, you need to supply multiple separate values, not a single comma-separated string inside one field.
Google's format guidance is explicit: the attribute should provide "short bulleted lists of the most relevant highlights of your products". Each value should be a sentence fragment that answers a common consumer question or surfaces an important product attribute. Highlights must describe only the product itself—no promotional text, no pricing, no competitor comparisons, and no links.
For a text feed, multiple highlight values are separated by commas, and any value containing a comma must be wrapped in straight double quotes. For the Merchant API, the field is submitted as a repeated resource property. Keep these format rules in mind as you decide how to store the data inside Shopify.
Retrieving a Metafield Value via the Shopify Admin GraphQL API
Shopify stores metafields on several object types. For product-level highlights that apply regardless of variant, the metafield typically lives on the Product object. If a highlight is variant-specific—for example, a compatibility note that differs between a 100W and a 200W model—it can live on ProductVariant.
The Shopify Admin GraphQL API exposes metafield and metafields as fields on the ProductVariant object. Each metafield is identified by two values: a namespace and a key. You define both when you create the metafield definition in Shopify Admin or via the API. For example, a namespace of feed and a key of highlights is a reasonable convention for feed-specific data.
To retrieve a single metafield by namespace and key on a product variant, your GraphQL query would look like this (hypothetical example using a store's own namespace and key values):
{
productVariant(id: "gid://shopify/ProductVariant/123456789") {
id
sku
metafield(namespace: "feed", key: "highlights") {
value
type
}
}
}
Hypothetical example: The namespace
feedand keyhighlightsare illustrative. Your actual namespace and key depend on what was defined in your Shopify store. Always look up the namespace and key from your metafield definition before writing the query—do not guess or construct them from the product title.
The value field returns the stored string. If you stored highlights as a JSON list (using Shopify's list.single_line_text_field type), the value will be a JSON array such as ["Supports 2.4 GHz and 5 GHz Wi-Fi","1080p maximum resolution"]. If you stored it as a single single_line_text_field, the value is a plain string and you would need to decide how to split it into separate highlight entries.
The Admin GraphQL API requires the read_products access scope to query variant and metafield data. As noted in the Shopify API reference, the ProductVariant object "Requires read_products access scope."
Mapping Metafield Values to product_highlight in Your Feed
Once you have the raw metafield value from the API response, you need to transform it into the correct feed format. The steps depend on how the data was stored.
If the metafield is a JSON list: Parse the array and treat each element as one product_highlight value. Validate that each element is between 1 and 150 characters—Google documentation sets a hard limit of 1–150 characters per highlight and requires at least 2 and at most 100 highlights per product. Drop or truncate any element that exceeds 150 characters. Confirm you have at least 2 elements; if not, the item will not meet the minimum requirement and Google will disapprove it.
If the metafield is a plain text field with a delimiter: Split on your chosen delimiter (a pipe character | avoids the comma-escaping complexity that commas introduce in text feeds), then apply the same length validation.
Writing to the feed:
- For a text feed, join the validated highlight strings with commas. Wrap any string that itself contains a comma in straight double quotes.
- For the Merchant API, pass each highlight as a separate repeated value in the
productHighlightarray of the product resource. - For an XML feed, write a separate
<g:product_highlight>element for each value.
Do not concatenate all highlights into a single long string and pass it as one value. Google treats each comma-delimited segment as a separate highlight in text feeds, so an unquoted comma inside a highlight value will silently split that highlight into two fragments.
Content Rules That Apply to Metafield Values
Storing data in a metafield does not exempt it from Google's editorial requirements. When you write highlight content into metafields, make sure the values already conform to what Google will accept. Specific disqualifying content includes: promotional language (sale, % off, limited time), pricing information, links, all-caps emphasis, foreign characters used decoratively, and references to other products or categorization hierarchies.
Google also requires that highlights not duplicate data already submitted in title, description, or product_detail. If your metafield values were originally written as a product description, review them before mapping—a sentence that works in a paragraph description often needs to be rewritten as a standalone sentence fragment to function as a highlight.
For feed operators using Magicfeedpro, the platform supports custom field mapping so you can point a destination feed attribute like product_highlight to a source field populated from a Shopify metafield pull, applying transformations such as JSON parsing and length enforcement before the values reach Merchant Center.
Common Problems to Check
- Wrong namespace or key: The GraphQL query returns
nullfor the metafield value. Confirm the exact namespace and key from your Shopify metafield definition. These are case-sensitive. - Fewer than 2 highlights: Google will disapprove the item. Ensure your metafield always contains at least 2 valid entries, or add a fallback that generates highlights from other product fields when the metafield is empty.
- Value exceeds 150 characters: Each highlight has a hard limit. A value that fits in a Shopify text field can easily exceed 150 characters.
- Repeated field formatted as a single value: Passing all highlights as one long string instead of separate repeated values is a common mapping mistake. Check the actual payload your feed tool sends to Merchant Center.
- Promotional language in stored metafields: Content written for on-site display often includes phrases like "Buy now" or "Free shipping." Strip these before mapping to
product_highlight.
Mapping a Shopify metafield to product_highlight is a straightforward pipeline once the namespace, key, and format requirements are clear. The two non-negotiable constraints are Google's character limit per highlight and the minimum of 2 highlights per product—both apply whether the data originates from a metafield, a manual feed edit, or any other source.
Related articles
Shopify Catalog Price Consistency Before Export
Check Shopify variant prices, compare-at prices, and landing page alignment before sending a catalog feed to Google.
Shopify Metafields Google Shopping Feed Attributes
Map Shopify metafields to Google Shopping feed attributes like product_detail and product_highlight in under a day — no developers needed, no data wasted.
Shopify Variants Google Shopping Feed: Split or Consolidate?
Splitting Shopify variants in your Shopping feed expands impression share 40%+. Learn which SKUs to split vs. consolidate to capture long-tail queries rivals