# Product data mapping for Stripe Agentic Commerce Suite

Understand how Product data maps to Stripe fields.

The following sections define the field-level mapping required to transform product data from your Project into Stripe Product Catalog specifications. It identifies direct mappings, required data transformations, and implementation recommendations for syncing product variants from commercetools to Stripe.

Instead of defining these mappings manually, you can use the Smart Data Modeler with agentic channels to analyze a sample of your catalog, generate a platform-ready Product Type, and map and transform your full catalog data to the fields Stripe Agentic Commerce Suite requires so you can import it into your Project.

For the full workflow, see [Smart Data Modeler - Agentic channels](/merchant-center/ai-agents/sdm-agentic-channels.md).

## Core Product identifiers

If using `brand`, `gtin` or `mpn`, you must create Variant-level Attributes for these fields. These Attributes should be of type [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `id` | `variant.sku` | Required | Must be fewer than 100 characters. |
| `title` | `productData.name[<locale>]` | Required | You should remove promotional text and avoid all capital letters. Must be fewer than 150 characters. |
| `description` | `productData.description[<locale>]` | Required | Should be plain text without links. Must be fewer than 5000 characters. |
| `link` | `productData.slug[<locale>]` combined with a base URL | Required | A direct link to the product page. For example: `https://example.com/en/products/{productData.slug[en]}`.By default, the base URL is read from `store.custom.fields.sellerStoreUrl`, but you can modify the template to pull it from another source or hardcode it. |
| `brand` | `variant.attributes["brand"]` | Optional | Not required for movies, books, and musical recording brands. Must be fewer than 70 characters. |
| `gtin` | `variant.attributes["gtin"]` | Optional | Must be fewer than 50 characters and not contain spaces or hyphens. |
| `mpn` | `variant.attributes["mpn"]` | Required, if `gtin` is not defined | Must be fewer than 70 characters. |

## Media

The recommended minimum dimensions of images in `image_link` and `additional_image_link` are `800`x`800` pixels.

The `video_link` and `model_3d_link` fields require Variant-level Attributes called `video` and `model_3d`. These Attributes should be of type [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `image_link` | `variant.images[0].url` | Required | Must be a publicly accessible link to a JPEG or PNG file. |
| `additional_image_link` | `variant.images.slice(1).map(img => img.url).join(',')` | Optional | Provides a string containing multiple links to images. You can provide up to 10 links to images. Each link must be to a publicly accessible link to JPEG or PNG. |
| `video_link` | `variant.attributes["video"]` | Optional | Must be a publicly accessible link to a YouTube, Vimeo, or MP4 video. A video length of 15-60 seconds is recommended. |
| `model_3d_link` | `variant.attributes["model_3d"]` | Optional | Must be a publicly accessible link to a GLB or GLTF file. A file size under 20 MB is recommended. |

## Item information

If defining `length`, `width`, or `height`, you must define all three fields and use the same unit of measurement for each (either `cm` or `in`).

If using `condition`, `google_product_category`, `age_group`, `material`, `length`, `width`, `height`, or `weight`, you must create Variant-level Attributes for these fields. The Attribute types can vary based on your implementation. For example, [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType) or [AttributeEnumType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeEnumType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `condition` | `variant.attributes["condition"]` | Required, if the product is not `new` | Can be `new`, `refurbished`, or `used`. |
| `google_product_category` | `variant.attributes["google_category_id"]` | Optional | Use the [Google product category](https://support.google.com/merchants/answer/6324436). |
| `product_category` | Use [Reference Expansion](/api/general-concepts.md#reference-expansion) on `productData.categories[0]` and join `productData.categories[0].obj.ancestors.obj.name[<locale>]` | Required, if `google_product_category` is not defined. | Select the deepest (most specific) Category assigned to the product.Recursively traverse the selected Category's parent path using the Category list.Join the localized names with `>`. For example, `[Root Category] > [Parent Category] > [Child Category]` becomes `Apparel & Accessories > Shoes > Running Shoes`. |
| `age_group` | `variant.attributes["ageGroup"]` | Optional | Can be:`newborn` (0-3 months old)`infant` (3-12 months old)`toddler` (1-5 years old)`kids` (5-13 years old)`adult` (teens or older). |
| `material` | `variant.attributes["material"]` | Required, if needed to differentiate different products in a set of variants. | Must be fewer than 100 characters. |
| `length` | `variant.attributes["length"]` | Optional | A string containing the number and unit, for example `100 cm`. Supports decimal values. |
| `width` | `variant.attributes["width"]` | Optional | A string containing the number and unit, for example `50 cm`. Supports decimal values. |
| `height` | `variant.attributes["height"]` | Optional | A string containing the number and unit, for example `30 cm`. Supports decimal values. |
| `weight` | `variant.attributes["weight"]` | Optional | A string containing the number and unit, for example `2 kg`. Supports `lb`, `oz`, `g`, and `kg`. |

## Product variants

If using `color`, `size`, `size_system`, or `gender`, you must create Variant-level Attributes for these fields. The Attribute types can vary based on your implementation. For example, [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType) or [AttributeEnumType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeEnumType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `item_group_id` | `productData.key` | Required, if variants exist | Must match the Stripe Field `id` used in the Product Feed. |
| `item_group_title` | `productData.name[<locale>]` | Optional | Provides a name for the variant group. Avoid using all capital letters. Must be fewer than 150 characters. |
| `color` | `variant.attributes["color"]` | Optional | Must be fewer than 40 characters. |
| `size` | `variant.attributes["size"]` | Optional | Recommended for clothing. Must be fewer than 20 characters. |
| `size_system` | `variant.attributes["sizeSystem"]` | Optional | A [CountryCode](/urn?urn=ctp%3Aapi%3Atype%3ACountryCode) for a clothing size system. For example: `US`. |
| `gender` | `variant.attributes["gender"]` | Optional | Recommended for clothing. Must be `male`, `female`, or `unisex`. |

## Availability and inventory

`expiration_date` requires a Variant-level Attribute called `expirationDate`. This Attribute should be of type [AttributeDateType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeDateType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `availability` | `variant.availability.isOnStock` | Required | If `true`, the value is `in_stock`. Otherwise `out_of_stock`. |
| `expiration_date` | `variant.attributes["expirationDate"]` | Optional | A date value. For example: `2026-02-24`. |
| `inventory_quantity` | `variant.availability.availableQuantity` | Optional | Must be a non-negative integer. |

## Price and promotions

If using `stripe_product_tax_code` or `applicable_fees`, you must create Variant-level Attributes for these fields. These Attributes should be of type [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `price` | Join `productData.variants[*].price.value.centAmount` and `productData.variants[*].price.currencyCode` | Required | Convert the `centAmount` to decimal based on `price.value.fractionDigits`.Include the target market context using the `priceCurrency` and `priceCountry` query parameters (`?priceCurrency=USD&priceCountry=US`)For example: `15.00 USD`. |
| `sale_price` | Join `productData.variants[*].price.discounted.value.centAmount` and `productData.variants[*].price.discounted.currencyCode` | Optional | Convert the `centAmount` to decimal based on `price.discounted.value.fractionDigits`.Include the target market context using the `priceCurrency` and `priceCountry` query parameters (`?priceCurrency=USD&priceCountry=US`)For example: `12.00 USD`. |
| `sale_price_effective_date` | `price.discounted.validFrom` and `price.discounted.validUntil` | Required, if `sale_price` is defined | Combine the `validFrom` and `validUntil` date values with a `/` separator.Include the target market context using the `priceCurrency` and `priceCountry` query parameters (`?priceCurrency=USD&priceCountry=US`)For example: `2025-12-01/2025-12-15`. |
| `stripe_product_tax_code` | `variant.attributes["stripeTaxCode"]` | Required, if using Stripe Tax for tax calculation | [Product tax codes](https://docs.stripe.com/tax/tax-codes) |
| `tax_behavior` | Use [Reference Expansion](/api/general-concepts.md#reference-expansion) on `taxCategory` and use `taxCategory.obj.rates[*].includedInPrice` | Optional | If `true`, it maps to an enum string `inclusive`. If `false`, it maps to an enum string `exclusive`. |
| `applicable_fees` | `variant.attributes["fees"]` | Optional | Use the format `country:region:fee_label:amount`. For example: `US:CA:Recycling Fee:0.25 USD`. |

## Shipping

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `shipping` | Use [Reference Expansion](/api/general-concepts.md#reference-expansion) on `shippingMethod.zoneRates[*].zone`.Join `shippingMethod.zoneRates[*].zone.obj.locations[*].country` : `shippingMethod.zoneRates[*].zone.obj.locations[*].state` : `shippingMethod.name` : `shippingMethod.zoneRates[*].shippingRate[*].price` | Required for shippable goods | Use the format `country:region:service:speed_range:price`. For example: `US:ALL:Standard Shipping:3-5:0.00 USD`. |
| `free_shipping_threshold` | `shippingMethod.zoneRates[*].shippingRates[*].freeAbove` | Optional | Use the format `country:price`. For example: `US:16.00 USD`. |

## Review and performance

If using `popularity_score`, `return_rate`, `product_review_count`, or `product_review_rating`, you must create Variant-level Attributes for these fields. These Attributes should be of type [AttributeNumberType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeNumberType) or [AttributeTextType](/urn?urn=ctp%3Aapi%3Atype%3AAttributeTextType).

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `popularity_score` | `variant.attributes["popularity_score"]` | Optional | Must be a number between `0` and `5`. |
| `return_rate` | `variant.attributes["return_rate"]` | Optional | Must be a number between `0` and `100`. |
| `product_review_count` | `variant.attributes["product_review_count"]` | Optional | The total number of reviews. Must be a non-negative integer. |
| `product_review_rating` | `variant.attributes["product_review_rating"]` | Required, if `product_review_count` is more than `0` | The average rating of the Product between `1` and `5`. |

## Feed processing instructions

| Stripe Field | Related commercetools field | Required | Mapping Logic |
| --- | --- | --- | --- |
| `delete` | If the fetch returns `404` | Optional | HTTP Status `404` must be interpreted as an indication to delete the Product or Product Variant. When `true`, the system removes the product or variant from the feed. If `false` or not defined, the product/variant is processed as normal. |

## Related pages

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