# Product data mapping for Google

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](https://support.google.com/merchants/answer/7052112). 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](/api/projects/custom-fields.md) called `storeUrl` on the [Store](/urn?urn=ctp%3Aapi%3Atype%3AStore) type. This Custom Field should be a [CustomFieldStringType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldStringType) 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](/urn?urn=ctp%3Aapi%3Atype%3AProductVariant) 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](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType).

| 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](/urn?urn=ctp%3Aapi%3Atype%3AAttributeEnumType).

| 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](https://support.google.com/merchants/answer/6324436). 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](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType) 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](https://support.google.com/merchants/answer/6150006) 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. |

## Related pages

- [Area overview page with navigation](/agentic-commerce.md)