Understand how Product information maps to Google Merchant Center fields.
This page defines the field-level mapping required to transform product data from commercetools into the Google Merchant Center product data specification. It covers core product identifiers, content fields, variant grouping, and product detail attributes.
Core product identifiers
These fields uniquely identify each product in Google Merchant Center.
By default, the link field is constructed using a Custom Field called
storeUrl on the Store type. This Custom Field should be a CustomFieldStringType containing your storefront URL. Alternatively, you can modify the template to source the base URL from another field or hardcode it.| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
id | variant.sku | Required | Use the sku of the ProductVariant as the unique product identifier. Must be stable, unique, and a maximum of 50 characters. Use the same ID for the same product across countries or languages. |
title | productData.name[<locale>] | Required | Use the localized Product name. Limit to 150 characters. Include distinguishing features such as color or size. Don't include promotional text. |
description | productData.description[<locale>] | Required | Use the localized Product description. Limit to 5000 characters. Must be accurate and descriptive. |
link | store.custom.fields.storeUrl and productData.slug[<locale>] | Required | Construct the full product URL by combining the Store URL with the product slug. For example: https://example.com/en/products/{productData.slug[en]}. Maximum of 2000 characters. Must use https. |
Product identifiers (GTIN/MPN/Brand)
If using
gtin, mpn, or brand, you must create Variant-level Attributes for these fields. These Attributes should be of type AttributeTextType.| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
gtin | variant.attributes.gtin | Strongly recommended | The Global Trade Item Number (UPC/EAN/JAN/ISBN). Maximum of 50 numeric characters. |
mpn | variant.attributes.mpn | Required, if gtin is not defined | The Manufacturer Part Number. Maximum of 70 characters. |
brand | variant.attributes.brand | Conditionally required | Required for all new products, except movies, books, and musical recording brands. Maximum of 70 characters. For products without a brand, leave the field empty rather than using placeholder values. |
identifier_exists | Derived from gtin, mpn, and brand | Optional | A Boolean indicating whether product identifiers are available. Set to false if no GTIN or MPN is available. Default: true. |
Product content
If using
product_highlight or product_detail, you must create Variant-level Attributes for these fields.| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
product_highlight | variant.attributes.highlights | Optional | Extract key features as bullet points. Minimum of 2, maximum of 100 entries. Maximum of 150 characters each. For example: ["Supports Netflix", "4k resolution"]. |
product_detail | variant.attributes | Optional | Map custom Attributes to the format section_name:attribute_name:attribute_value. section_name is optional. Multiple values are separated by commas. |
Variant grouping
These fields group product Variants under a common parent product.
| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
item_group_id | Parent product SKU or productData.key | Conditionally required | Required if variants exist. Use the parent product SKU consistently across all Variants. Maximum of 50 characters. Required for free listings for all product Variants. |
color | variant.attributes.color | Conditionally required | Required for apparel in select regions (Brazil, France, Germany, Japan, UK, US). Maximum of 100 characters. For example: Navy Blue. |
size | variant.attributes.size | Conditionally required | Required for apparel in select regions. Maximum of 100 characters. For example: Large, 10. |
material | variant.attributes.material | Conditionally required | Required if relevant for distinguishing different products in a set of Variants. Maximum of 200 characters. For example: Leather, Cotton. |
pattern | variant.attributes.pattern | Conditionally required | Required if relevant for distinguishing different products in a set of Variants. For example: Striped, Solid. |
Apparel-specific attributes
If selling apparel products, you must create Variant-level Attributes for the following fields using AttributeEnumType.
| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
age_group | variant.attributes.ageGroup | Conditionally required | Required for all apparel products targeted to people in Brazil, France, Germany, Japan, the UK, and the US. Accepted values: newborn (0-3 months), infant (3-12 months), toddler (1-5 years), kids (5-13 years), adult (13+). |
gender | variant.attributes.gender | Conditionally required | Required for all apparel items targeted to people in Brazil, France, Germany, Japan, the UK, and the US, and for all gender-specific products. Accepted values: male, female, unisex. |
size_type | variant.attributes.sizeType | Optional | Accepted values: regular, petite, maternity, big, tall, plus. Default: regular. Up to 2 values. |
size_system | variant.attributes.sizeSystem | Optional | Map to the region code. Accepted values: US, UK, EU, DE, FR, JP, CN, IT, BR, MEX, AU. |
Product detail attributes
| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
condition | variant.attributes.condition | Conditionally required | Required if not new. Accepted values: new, refurbished, used. Default: new. |
adult | variant.attributes.adult | Conditionally required | Required if the product contains adult content. Accepted values: yes, no. |
multipack | variant.attributes.multipack | Conditionally required | Required if the product is a multipack. Provide the quantity as a whole number. Required for select countries (Australia, Brazil, Czechia, France, Germany, Italy, Japan, Netherlands, Spain, Switzerland, the UK, and US). |
is_bundle | variant.attributes.isBundle | Conditionally required | Required if the product is a bundle. Accepted values: yes, no. Required for select countries. |
certification | variant.attributes.certification | Conditionally required | Required for products that require certain certification information (for example, energy efficiency ratings). Format: authority:name:code. For example: EC:EPREL:123456. Available for EU, EFTA countries, and the UK. |
Product categories
| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
google_product_category | variant.attributes.googleCategoryId | Recommended | Use Google's product taxonomy. Provide the numeric category ID or full path. For example: Apparel & Accessories > Clothing > Dresses or 2271. |
product_type | productData.categories[].ancestors[].name[<locale>] | Optional | Expand Category references and join the category path with >. Maximum of 750 characters. Use your full retailer category hierarchy. For example: Home > Kitchen > Appliances > Blenders. |
Custom labels
Custom labels allow you to organize products for campaign management. You must create Variant-level Attributes of type AttributeTextType for each label.
| Google Merchant Center field | Related commercetools field | Required | Mapping logic |
|---|---|---|---|
custom_label_0 | variant.attributes.customLabel0 | Optional | Maximum of 100 unique values. For example: seasonal_sale. |
custom_label_1 | variant.attributes.customLabel1 | Optional | Maximum of 100 unique values. |
custom_label_2 | variant.attributes.customLabel2 | Optional | Maximum of 100 unique values. |
custom_label_3 | variant.attributes.customLabel3 | Optional | Maximum of 100 unique values. |
custom_label_4 | variant.attributes.customLabel4 | Optional | Maximum of 100 unique values. |
promotion_id | variant.attributes.promotionId | Optional | Maximum of 10 per product. Case-sensitive. |
Native checkout fields
The following additional fields are required to enable native checkout through the Universal Commerce Protocol (UCP). These fields are sent through the supplemental data source.
| Google Merchant Center field | Type | Required | Description |
|---|---|---|---|
native_commerce | Product attribute | Required | Eligibility flag for native checkout. Ensure product restrictions compliance. |
merchant_item_id | Custom attribute | Optional | Use when the Offer ID does not match the product ID defined in the Checkout component. |
consumer_notice.consumer_notice_type | Custom attribute | Conditionally required | Regulatory warning requirements. Accepted values: legal_disclaimer, safety_warning, prop_65. |
consumer_notice.consumer_notice_message | Custom attribute | Conditionally required | Warning message displayed prominently on the checkout screen. |
return_policy_label | Custom attribute | Optional | Override return policy per product if needed. |