Product catalogPrivate preview

Learn how to share structured product and inventory data with Stripe for AI agent discovery.

Use the product and inventory feed specification to share structured product and stock data with Stripe and distribute your catalog to AI agents for search and shopping. You can begin with a full product feed submission, then send incremental inventory feed updates to keep stock levels and availability current.

Product feed specification

Use the product feed to provide your complete structured catalog (for example, titles, descriptions, identifiers, pricing, fulfillment, and media). Each row represents a product or variant.

Prepare your feed: Format your catalog using the field reference in this document. Each field includes sample values, validation rules, and whether it’s required, recommended, or optional.
Deliver the feed: Send the feed securely using the Stripe API in CSV format (integration details to come). Each row represents one product or variant. Submit a full initial feed to the sandbox endpoint to validate that your data parses correctly and meets all field requirements before pushing to production.
Index and clean your data: We validate and clean your data, index it into the Stripe Catalog, and convert it to the format each agent requires.
Keep your data current: Refresh your feed frequently. Any changes to product attributes, pricing, or fulfillment details should be updated as soon as they occur to maintain customer trust and prevent stale listings.

Feed processing mode

Product feed uploads use upsert mode, where each row represents an insert or update for a product identified by its id.

If the id doesn’t exist, we create the product.
If the id already exists, we update the product with the values provided in that row.
Products not included in the file remain unchanged.

Deletion behavior

To remove a product or variant through the feed, include the optional delete column in your CSV. Set true for any products you want to delete. For products you want to keep, set false or leave the field blank.

Product catalog field reference

Review the full schema used by the Stripe catalog in the following sections. Each table lists data types, examples, and requirements.

Basic product data

Provide the essential identifiers and descriptive text that uniquely define each product.

Field	Data type	Example	Requirement	Notes
id	String (alphanumeric)	`SKU12AB3456`	Required	Your product’s unique identifier Use the product’s SKU where possible Maximum 100 characters Keep the ID the same when updating your data
title	String (UTF-8 text)	`Mens Floral Polo Shirt`	Required	Your product’s title Accurately describe your product and match the title from your landing page. Maximum 150 characters Avoid all-caps
description	String (UTF-8 text)	`Bring a burst of fun to your golf game with this Men's Floral Polo`	Required	Your product’s description Include only information about the product. Don’t include links to your store, sales information, details about competitors, other products, or accessories Maximum 5000 characters Plain text only
link	URL (RFC 1738)	`https://example.com/product/SKU12AB3456`	Required	Your product’s landing page Use your verified domain name Start with `http` or `https` (`https` preferred) Must resolve with `http` 200 (no broken links)

Product identifiers

Use these globally recognized identifiers to help differentiate your products for search and matching.

Field Data type Example Requirement Notes

Field	Data type	Example	Requirement	Notes
brand	String	`Stripe`	Required for all excluding movies, books, and musical recording brands	Your product’s brand name Provide the brand name of the product generally recognized by consumers. Maximum 70 characters
gtin	String (Numeric GTIN, UPC, ISBN)	`3234567890126`	Recommended	Your product’s global trade item number (GTIN) Maximum 50 characters Exclude dashes and spaces
mpn	String (alphanumeric)	`STR12345`	Required if GTIN is missing	Your product’s manufacturer part number (MPN) Only submit MPNs assigned by a manufacturer Maximum 70 characters

brand

String

Stripe

Required for all excluding movies, books, and musical recording brands

Your product’s brand name

Provide the brand name of the product generally recognized by consumers.
Maximum 70 characters

gtin

String

(Numeric GTIN, UPC, ISBN)

3234567890126

Recommended

Your product’s global trade item number (GTIN)

Maximum 50 characters
Exclude dashes and spaces

mpn

String

(alphanumeric)

STR12345

Required if GTIN is missing

Your product’s manufacturer part number (MPN)

Only submit MPNs assigned by a manufacturer
Maximum 70 characters

Media

Provide visual and optional rich media to represent the product accurately.

Field	Data type	Example	Requirement	Notes
image_link	URL (RFC 1738)	`https://example.com/image1.jpg`	Required	The URL of your product’s main image Use JPEG or PNG format Must start with `http` or `https` (`https` preferred) Must be publicly accessible Recommended minimum size: 800 × 800 px Avoid watermarks, text overlays, or promotional graphics
additional_image_link	URL array (RFC 1738)	`https://example.com/image2.jpg,…`	Optional	The URLs of additional images for your product Follow the same requirements as `image_link` Maximumimum of 10 images supported Use multiple angles, packaging, or in-context views To submit one image, submit the (encoded) URL: `https://www.example.com/image2.jpg` To submit more than one image (up to 10), separate each URL with a comma (for example, `https://www.example.com/image2.jpg,https://www.example.com/image3.jpg`) Make sure to encode any commas (as %2C) within the URL, but don’t encode the comma that you use to separate each image URL: `https://www.example.com/image2%2C3.jpg,https://www.example.com/image2%2C4.jpg`
video_link	URL (RFC 1738)	`https://youtu.be/12345`	Optional	A product video showcasing your product in use or during unboxing Must be publicly accessible (for example, YouTube, Vimeo, or a direct MP4 link) Recommended formats: MP4, MOV, or WebM Recommended duration: 15–60 seconds Include audio only if relevant to the product (for example, sound demo) Make sure that you clearly show the same product as in the main image
model_3d_link	URL (RFC 1738)	`https://www.example.com/products/xyz.glb`	Optional	Additional link to show a 3D model of your product Preferred formats: GLB or GLTF Must be publicly accessible Keep file size under 20 MB for optimal loading Make sure the model accurately represents the product’s physical form and color

Item information

Describe physical characteristics and classification for accurate filtering and taxonomy placement.

Field	Data type	Example	Requirement	Notes
condition	Enum (`new`, `refurbished`, `used`)	`new`	Required if product condition differs from new	The condition of your product at time of sale `new`: Brand-new item in original, unopened packaging `refurbished`: Professionally restored to working order, includes a warranty, and the original packaging may be missing `used`: Previously used, with original packaging opened or missing
google_product_category	String (Value from the Google product taxonomy. The numerical category ID, or the full path of the category.)	`2271` or `Apparel & Accessories > Clothing > Dresses`	Recommended	Predefined Google product category Include only the most relevant category Include either the full category path or the numerical category ID, but not both. Use the category ID when possible.
product_category	String (Category taxonomy)	`Apparel & Accessories > Clothing > Outerwear`	Required if `google_product_category` is missing	Product category that you define for your product Use `>` as separator Include the full category Exclude dashes and spaces
age_group	Enum (`newborn`, `infant`, `toddler`, `kids`, `adult`)	`infant`	Optional	The demographic for which your product is intended `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	String	`leather`	Required if it’s relevant for distinguishing different products in a set of variants	Your product’s primary fabric or material Maximum 100 characters
length	Number and unit (`cm` and `in`)	`20 in`	Optional	Your product’s length Use the same unit of measurement for each product dimension attribute (including product length, width, and height) Decimal values are supported
width	Number and unit (`cm` and `in`)	`20 in`	Optional	Your product’s width Use the same unit of measurement for each product dimension attribute (including product length, width, and height) Decimal values are supported
height	Number and unit (`cm` and `in`)	`20 in`	Optional	Your product’s height Use the same unit of measurement for each product dimension attribute (including product length, width, and height) Decimal values are supported
weight	Number and unit (`lb`, `oz`, `g`, `kg`)	`2.5 lb`	Optional	Your product’s weight Use the actual assembled product weight for this attribute Decimal values are supported

Variants

Define variant relationships, such as color and size, so that related SKUs group under one parent. If you submit variants, you must include the same item_group_id for every variant.

Field	Data type	Example	Requirement	Notes
item_group_id	String	`Shoe1234`	Required if variants exist	ID for a group of products that come in different variants Use a unique value for each group of variants. Use the parent SKU where possible. Keep the value the same when updating your product data Maximum 70 characters Use the same set of variant attributes for all products that share the same `item_group_id`. For example, if a dress is availabile in two colors and two sizes, each variant must include values for both color and size.
item_group_title	String (UTF-8 text)	`Shoes`	Optional	Your product group’s title Use a clear, human-readable name that represents the group of related variants (for example, “Men’s Running Shoes”) Maximum 150 characters Avoid using all capital letters
color	String	`Black`	Recommended (apparel)	Your product’s color If your product features multiple colors, list the primary color. Maximum 40 characters
size	String	`10`	Recommended (apparel)	Your product’s size Maximum 20 characters
size_system	Country code (ISO 3166)	`US`	Recommended (apparel)	Size system Two-letter country code
gender	Enum (`male`, `female`, `unisex`)	`male`	Recommended (apparel)	Your product’s intended gender

Availability and inventory

Provide live stock status and quantities to maintain purchase accuracy.

Field	Data type	Example	Requirement	Notes
availability	Enum (`in_stock`, `out_of_stock`, `preorder`, `backorder`)	`in_stock`	Required for all products	Your product’s availability
availability_date	Date (ISO 8601)	`2026-02-24`	Required if product availability is set to `preorder`	The date a pre-ordered product becomes available for delivery
expiration_date	Date (ISO 8601)	`2026-12-31`	Optional	The date your product stops showing
inventory_not_tracked	Boolean (`true` or `false`)	`false`	Optional	Specifies whether your product’s inventory is tracked. `true`: Inventory isn’t tracked (for example, digital goods or made-to-order). `inventory_quantity` must be blank. `false`: Inventory is tracked and `inventory_quantity` is required
inventory_quantity	Integer (Non-negative integer)	`100`	Required if `inventory_not_tracked` is `false`. Leave blank if `true`.	Sellable units available for this item. Leave blank if `inventory_not_tracked` is `true`.

Price and promotions

Specify pricing information for display and promotional logic.

Field	Data type	Example	Requirement	Notes
price	Number and currency (ISO 4217)	`15.00 USD`	Required for all products	Your product’s price
sale_price	Number and currency (ISO 4217)	`12.99 USD`	Optional	Discounted price
sale_price_effective_date	Date (ISO 8601)	`2025-12-01/2025-12-15`	Required if you provided `sale_price`	Sale window Separate the start date and end date with `/`
stripe_product_tax_code	String (Stripe Product Tax Code (PTC))	`txcd_99999999`	Required if using Stripe Tax for tax calculation	Use Stripe’s Product Tax Codes to classify your product for accurate tax calculation. These codes help Stripe determine the correct tax rate based on product type and jurisdiction.
tax_behavior	Enum (`inclusive` or `exclusive`)	`exclusive`	Optional	Specifies whether your product’s price includes applicable taxes (inclusive) or excludes them (exclusive). If omitted, the default value is exclusive.
applicable_fees	String (`country:region:fee_label:fee_amount`: Put each option as a colon-delimited value, and separate multiple entries with commas.)	`US:CA:Recycling Fee:0.25 USD,DE:ALL:Bottle Deposit:0.10 EUR`	Optional (required where regulatory or regional fees apply)	Use this field to specify per-unit fees and surcharges that apply based on product type and region. These fees should not be included in the base product price; they are intended to appear as separate line items at checkout and in reporting. Format each fee as a colon-delimited value: `country` (Required): ISO 3166-1 alpha-2 country code (for example, US or DE). `region` (Required): Provide a region, state, territory, or prefecture (for example, CA). Use `ALL` to apply to all regions or provinces within the specified country. `fee_label` (Required): Human-readable name for the fee (for example, recycling fee, bottle deposit, or eco charge). Don’t use colons in the name. `fee_amount` (Required): Fixed per-unit fee using a period as the decimal separator and ISO 4217 currency code (for example, 5.00 USD).

Fulfillment

Provide shipping options, rates, and estimated delivery times.

Field Data type Example Requirement Notes

Field	Data type	Example	Requirement	Notes
shipping	String (`country:region:service:speed_range:price`: Put each option as a colon-delimited value, and separate multiple entries with commas.)	`US:ALL:Standard Shipping:3-5:0.00 USD,US:ALL:Expedited Shipping:1-2:12.99 USD`	Required if the product is shippable (for example, a physical good)	Your product’s shipping cost, shipping speeds, and the locations your product ships to. Format each shipping option as a colon-delimited value: `country` (Required): Provide a ISO 3166-1 alpha-2 country code indicating the country the product can be delivered to (for example, US, DE) `region` (Required): Provide a region, state, territory, or prefecture using the ISO 3166-2 subdivision code (US subdivision code), without the country prefix (for example, VA or NY). Use ALL as a wildcard to indicate that the shipping rule applies to all regions or provinces within the specified country. `service` (Required): Human-readable name for the service (for example, standard or express shipping options). `speed_range` (Optional): Minimum and maximum number of days needed for shipping (for example, 3-5) `price` (Required): Submit a fixed shipping cost and use a period as the decimal separator and ISO 4217 currency code (for example, 3.00 USD)
free_shipping_threshold	String (`country:price`)	`US:16.00 USD`	Optional	Order total at or above which shipping is free `country` (Required): ISO 3166-1 alpha-2 country code `price_threshold` (Required): Order total at or above which shipping is free

shipping

String

(country:region:service:speed_range:price: Put each option as a colon-delimited value, and separate multiple entries with commas.)

US:ALL:Standard Shipping:3-5:0.00 USD,US:ALL:Expedited Shipping:1-2:12.99 USD

Required if the product is shippable (for example, a physical good)

Your product’s shipping cost, shipping speeds, and the locations your product ships to.

Format each shipping option as a colon-delimited value:
- country (Required): Provide a ISO 3166-1 alpha-2 country code indicating the country the product can be delivered to (for example, US, DE)
- region (Required): Provide a region, state, territory, or prefecture using the ISO 3166-2 subdivision code (US subdivision code), without the country prefix (for example, VA or NY). Use ALL as a wildcard to indicate that the shipping rule applies to all regions or provinces within the specified country.
- service (Required): Human-readable name for the service (for example, standard or express shipping options).
- speed_range (Optional): Minimum and maximum number of days needed for shipping (for example, 3-5)
- price (Required): Submit a fixed shipping cost and use a period as the decimal separator and ISO 4217 currency code (for example, 3.00 USD)

free_shipping_threshold

String

(country:price)

US:16.00 USD

Optional

Order total at or above which shipping is free

country (Required): ISO 3166-1 alpha-2 country code
price_threshold (Required): Order total at or above which shipping is free

Performance and review signals

Share performance and review signals to help AI agents and ranking systems identify high-quality, trusted products.

These fields are optional but recommended. They improve discovery, ranking, and personalization on across agentic interfaces.
Provide only aggregated metrics and exclude any user-level data or personally identifiable information.
Update these metrics periodically (for example, weekly) to maintain accuracy.

Field	Data type	Example	Requirement	Notes
popularity_score	Number (0–5 scale)	`4.7`	Recommended	Aggregate popularity indicator for this product or variant Use a consistent 0-5 scale across your catalog (0 = lowest, 5 = highest) Derive this from signals such as views, add-to-cart events, conversions, or sales rank Use a consistent aggregation window (for example, last 90 days) to ensure freshness
return_rate	Number (0–100 (don’t include the `%` symbol))	`2.0`	Recommended	Percentage of units returned for this product or variant Express as a numeric percentage between 0 and 100 (for example, use 2.0 for 2%) Use a consistent aggregation window (for example, last 90 days)
product_review_count	Integer (Non-negative integer)	`124`	Recommended	Total number of reviews associated with this product or variant Match the population used to compute `product_review_rating` Use 0 if no reviews exist Reflect verified purchase reviews when possible
product_review_rating	Number (1–5 scale)	`4.3`	Required if `product_review_count` is greater than 0	Average review rating for this product or variant Use a consistent 1–5 scale across your catalog (1 = lowest, 5 = highest) Must correspond to the same dataset as `product_review_count` Leave this field blank if `product_review_count` is 0

Feed processing instructions

Defines operational fields that control how the system processes each row in the feed.

Field Data Type Example Requirement Notes

Field	Data Type	Example	Requirement	Notes
delete	Boolean (`true` or `false`)	`true`	Optional	Marks the product or variant for permanent removal When `true`, we remove the product identified by `id` and ignore all other columns in that row When omitted or `false`, the row is processed normally as an upsert

delete

Boolean

(true or false)

true

Optional

Marks the product or variant for permanent removal

When true, we remove the product identified by id and ignore all other columns in that row
When omitted or false, the row is processed normally as an upsert

Use the inventory feed specification

Use the inventory feed to refresh product availability and stock quantities without resubmitting your full catalog. Send frequent updates from your warehouse, point of sale, or fulfillment systems so your products reflect accurate in-stock status across agentic interfaces.

Keep your product feed in sync: The id values in your inventory file must already exist in the main catalog feed.
Send frequent inventory files: Push updates through the Stripe API in CSV format.
Send partial updates: Include only changed SKUs—missing SKUs retain their last known inventory state.

Inventory feed field reference

Inventory feed fields

Provide live stock status and quantities to maintain purchase accuracy.

Field	Data type	Example	Requirement	Notes
id	String (alphanumeric)	`SKU12AB3456`	Required	Must match the `id` in your primary product feed. This value is the key identifier
availability	Enum (`in_stock`, `out_of_stock`, `preorder`, `backorder`)	`in_stock`	Required for all products	Your product’s availability
availability_date	Date (ISO 8601)	`2026-02-24`	Required if product availability is set to `preorder`	The date a preordered product becomes available for delivery
inventory_quantity	Integer (Non-negative integer)	`100`	Required for all products	Sellable units