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. Start 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.

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.
Send the feed securely using the Stripe API in CSV format. Each row represents one product or variant. Submit a full initial feed to the sandbox endpoint to confirm your data parses correctly and meets all field requirements before you push to production.
Keep your data current and refresh your feed frequently. Update changes to product attributes, pricing, or fulfillment details when they occur to maintain customer trust and prevent stale listings. We validate and clean your data, index it into the Stripe Catalog, and convert it to the format each agent requires.

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 it to true for any products you want to delete. For products you want to keep, set it to false or leave the field blank.

When delete=true, Stripe only reads the id and delete columns for that row and ignores every other column.

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	Requirement
id	String (alphanumeric) Maximum 100 characters	Required
Your product’s unique identifier. Use the product’s SKU where possible and keep the ID the same when updating your data. Example: SKU12AB3456
title	String (UTF-8 text) Maximum 150 characters	Required
Your product’s title. Accurately describe your product and match the title from your landing page. Avoid all-caps. Example: Men’s Floral Polo Shirt
description	String (UTF-8 text) Maximum 5000 characters	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. Plain text only. Example: Bring a burst of fun to your golf game with this Men’s Floral Polo
link	URL (RFC 1738)	Required
Your product’s landing page. Use your verified domain name, starting with `https` (preferred) or `http`. Must resolve with `HTTP 200` (no broken links). Example: https://example.com/product/SKU12AB3456

Product identifiers

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

Field	Data type	Requirement
brand	String	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. Example: Stripe
gtin	String (Numeric GTIN, UPC, ISBN)	Recommended
Your product’s global trade item number (GTIN). Maximum 50 characters. Exclude dashes and spaces. Example: 3234567890126
mpn	String (alphanumeric)	Required if GTIN is missing
Your product’s manufacturer part number (MPN). Only submit MPNs assigned by a manufacturer. Maximum 70 characters. Example: STR12345

Media

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

Field	Data type	Requirement
image_link	URL (RFC 1738)	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. Example: https://example.com/image1.jpg
additional_image_link	URL array (RFC 1738)	Optional
The URLs of additional images for your product. Follow the same requirements as `image_link`. Maximum 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). Encode any commas (as `%2C`) within the URL, but don’t encode the comma that separates each image URL: https://www.example.com/image2%2C3.jpg,https://www.example.com/image2%2C4.jpg. Example: https://example.com/image2.jpg,…
video_link	URL (RFC 1738)	Optional
A product video that shows 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 it’s relevant to the product (for example, a sound demo). Make sure you show the same product as in the main image. Example: https://youtu.be/12345
model_3d_link	URL (RFC 1738)	Optional
An additional link that shows 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. Example: https://www.example.com/products/xyz.glb

Item information

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

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

Variants

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

Field	Data type	Requirement
item_group_id	String	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 you update 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 available in two colors and two sizes, each variant must include values for both color and size. Example: Shoe1234
item_group_title	String (UTF-8 text)	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 all caps. Example: Shoes
color	String	Recommended (apparel)
Your product’s color. If your product features multiple colors, list the primary color. Recommended length: 40 characters or fewer. Maximum length: 100 characters. Example: Black
size	String	Recommended (apparel)
Your product’s size. Maximum 20 characters. Example: 10
size_system	Country code (ISO 3166)	Recommended (apparel)
Size system. Two-letter country code. Example: US
gender	Enum (`male`, `female`, `unisex`)	Recommended (apparel)
Your product’s intended gender. Example: male

Custom variant options

Define non-standard characteristics for your product variants that aren’t already included in the Variants section using name and value pairs (for example, “Material/Oak” or “Pattern/Floral”).

Field	Data type	Requirement
custom_variant_option_name_{1-3}	String (UTF-8 text)	Optional
Defines a maximum of three custom product variant options. Number each column in the CSV 1-3: `custom_variant_option_name_1`, `custom_variant_option_name_2`, `custom_variant_option_name_3`. Each variant option name maps to the value with the same number. For example, `custom_variant_option_name_1` maps to `custom_variant_option_value_1`. Example: Material
custom_variant_option_value_{1-3}	String (UTF-8 text)	Optional
Sets custom product variant values to the variants defined by custom variant option names. Number each column in the CSV 1-3: `custom_variant_option_value_1`, `custom_variant_option_value_2`, `custom_variant_option_value_3`. Each variant option value maps to the name with the same number. For example, `custom_variant_option_value_1` is the value for `custom_variant_option_name_1`. Example: Oak

Availability and inventory

Provide live stock status and quantities to maintain purchase accuracy.

Field	Data type	Requirement
availability	Enum (`in_stock`, `out_of_stock`, `preorder`, `backorder`)	Required for all products
Your product’s availability. Example: in_stock
availability_date	Date (ISO 8601)	Required if product availability is set to `preorder`
The date a preordered product becomes available for delivery. Example: 2026-02-24
expiration_date	Date (ISO 8601)	Optional
The date your product stops showing. Example: 2026-12-31
inventory_not_tracked	Boolean (`true` or `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. Example: false
inventory_quantity	Integer (Non-negative integer)	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`. Example: 100

Price and promotions

Specify pricing information for display and promotional logic.

Field	Data type	Requirement
price	Number and currency (ISO 4217)	Required for all products
Your product’s price. Example: 15.00 USD
sale_price	Number and currency (ISO 4217)	Optional
Discounted price. Example: 12.99 USD
sale_price_effective_date	Date (ISO 8601)	Required if you provided `sale_price`
Sale window. Separate the start date and end date with `/`. Example: 2025-12-01/2025-12-15
stripe_product_tax_code	String (Stripe Product Tax Code (PTC))	Required if using Stripe Tax for tax calculation
Use Stripe Product Tax Codes to classify your product for tax calculation. These codes help Stripe determine the correct tax rate based on product type and jurisdiction. Example: txcd_99999999
tax_behavior	Enum (`inclusive` or `exclusive`)	Optional
Specifies whether your product’s price includes applicable taxes (inclusive) or excludes them (exclusive). If you omit this field, the default value is `exclusive`. Example: exclusive
applicable_fees	String `country:region:fee_label:fee_amount`: Put each option as a colon-delimited value, and separate multiple entries with commas.	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 aren’t included in the base product price. Use them 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): 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). Example: US:CA:Recycling Fee:0.25 USD,DE:ALL:Bottle Deposit:0.10 EUR

Fulfillment

Provide shipping options, rates, and estimated delivery times.

Field	Data type	Requirement
shipping	String `country:delivery_area:service:speed_range:price`: Put each option as a colon-delimited value, and separate multiple entries with commas.	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): ISO 3166-1 alpha-2 country code indicating the country the product can be delivered to (for example, US or DE). `delivery_area` (Required): One of the following values that defines where you can deliver the product: `region`: Region, state, territory, or prefecture using the ISO 3166-2 subdivision code without the country prefix (for example, `VA` or `NY`). Use `ALL` to apply to every region or province in the country. `postal_code`: Postal code or postal code range (currently supported only for the US). Allowed formats: Single code: `94012` Range: `73114-74547` Wildcard at the end: `94` Multiple wildcard ranges: `94-95` `service` (Required): Human-readable name for the service (for example, standard or express shipping). `speed_range` (Optional): Minimum and maximum number of days needed for shipping (for example, `3-5`). `price` (Required): Fixed shipping cost using a period as the decimal separator and ISO 4217 currency code (for example, `3.00 USD`). Example (Region): US:ALL:Standard Shipping:3-5:0.00 USD,US:ALL:Expedited Shipping:1-2:12.99 USD* *Example (Postal code): US:94012:Standard Shipping:3-5:0.00 USD,US:73114-74547:Expedited Shipping:1-2:9.99 USD,US:94:Expedited Shipping:1-2:9.99 USD,US:94-95:Standard Shipping:2-5:0.00 USD**
shipping_cost_basis	Enum (`per_order`, `per_item`)	Optional
Specifies how the shipping cost defined in the `shipping` field applies when customers buy multiple units of the same SKU. If you omit this setting, the default behavior is `per_order`. `per_order`: Charge the shipping price once per order for the matching shipping service, regardless of quantity. `per_item`: Charge the shipping price per unit of this SKU (that is, multiply by the quantity purchased). Example: per_item
free_shipping_threshold	String `country:region:service:price_threshold`: Put each option as a colon-delimited value, and separate multiple entries with commas.	Optional
Defines an order-level free shipping rule. When the order merchandise subtotal meets or exceeds the specified threshold, the shipping cost for the matching shipping service is `0.00`. Format each shipping option as a colon-delimited value: `country` (Required): ISO 3166-1 alpha-2 country code indicating the country the product can be delivered to (for example, US or DE). `region` (Required): Region, state, territory, or prefecture using the ISO 3166-2 subdivision code without the country prefix (for example, VA or NY). Use `ALL` to apply to all regions or provinces within the specified country. `service` (Required): Shipping service name. It must match a service defined in the `shipping` field (for example, standard or express shipping). `price_threshold` (Required): Order merchandise subtotal after item-level discounts and before tax and shipping, expressed as amount and currency. Use a period as the decimal separator and an ISO 4217 currency code (for example, `50.00 USD`). Example: US:ALL:Standard Shipping:50.00 USD,US:ALL:Expedited Shipping:100.00 USD

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 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	Requirement
popularity_score	Number (0–5 scale)	Recommended
Aggregate popularity indicator for this product or variant. Use a consistent 0 through 5 scale across your catalog (0 is the lowest, 5 is the highest). Derive this from signals such as views, add-to-cart events, conversions, or sales rank. Use a consistent aggregation window (for example, the last 90 days) to keep this value current. Example: 4.7
return_rate	Number 0–100 (don’t include the `%` symbol)	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, the last 90 days). Example: 2.0
product_review_count	Integer (Non-negative integer)	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. Example: 124
product_review_rating	Number (1–5 scale)	Required if `product_review_count` is greater than 0
Average review rating for this product or variant. Use a consistent 1 through 5 scale across your catalog (1 is the lowest, 5 is the highest). This value must correspond to the same dataset as `product_review_count`. Leave this field blank if `product_review_count` is `0`. Example: 4.3

Feed processing instructions

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

Field	Data type	Requirement
delete	Boolean (`true` or `false`)	Optional
Mark 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`, we process the row as an upsert. Example: true

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

Use the following reference to format your inventory feed fields.

Inventory feed fields

Provide live stock status and quantities to maintain purchase accuracy.

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

Use the price feed specification

Use the price feed to refresh pricing information for display and promotions without resubmitting your full catalog.

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

Price feed field reference

Use the following reference to format your price feed fields.

Price feed fields

Specify pricing information for display and promotional logic.

Field	Data type	Requirement
id	String (alphanumeric)	Required
Must match the `id` in your primary product feed. This value is the key identifier. Example: SKU12AB3456
price	Number and currency (ISO 4217)	Required for all products
Your product’s price. Example: 15.00 USD
sale_price	Number and currency (ISO 4217)	Optional
Discounted price. Example: 12.99 USD
sale_price_effective_date	Date (ISO 8601)	Required if you provided `sale_price`
Sale window. Separate the start date and end date with `/`. Example: 2025-12-01/2025-12-15