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.
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.| 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 800x800 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.| 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 or AttributeEnumType.| 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. |
product_category | Use 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 or AttributeEnumType.| 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 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.| 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.| 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 |
tax_behavior | Use 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 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 or AttributeTextType.| 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. |