OpenAI ACP Product Feed Spec: A Field-by-Field Walkthrough

If you’re scoping an OpenAI Agentic Commerce Protocol integration, the product feed spec is where most of the real work lives. The checkout and delegated payment specs get the marketing attention, but the feed is the gate. A feed that doesn’t validate doesn’t surface, and a feed that doesn’t surface doesn’t sell.

This is a field-by-field walkthrough of OpenAI’s ACP product feed, drawn from the file-upload spec. We’ll cover all 67 fields across 15 logical groups, flag the required versus optional split, and call out the validation gotchas worth catching before they cost you re-submissions.

If you want the conceptual context first, our agentic commerce shopping guide covers ACP at the strategy level, and the ACP vs UCP comparison sets the protocol choice in context.

The shape of the spec

ACP organises product data into 15 logical groups. The order below matches the published spec.

1. OpenAI Flags
2. Basic Product Data
3. Item Information
4. Media
5. Price & Promotions
6. Availability & Inventory
7. Variants
8. Fulfillment
9. Merchant Info
10. Returns
11. Performance Signals
12. Compliance
13. Reviews and Q&A
14. Related Products
15. Geo Tagging

Across these 15 groups there are roughly 67 fields. 15 are required, 12 are conditional or strongly recommended, and around 40 are optional. The optional fields are not optional in a competitive sense, they’re where ChatGPT result quality is won.

Two formats matter: file upload for daily full snapshots, and API for incremental updates and promotions. OpenAI recommends running both. The field shape below is the file-upload shape; the API shape is structurally similar with promotions added.

Group 1: OpenAI flags

Three fields, two required. These are the gating signals OpenAI uses to decide whether a product is eligible for search surfacing and checkout.

• is_eligible_search (required, boolean). Whether the product can surface in ChatGPT search results. The default of false means invisible, flip explicitly to true.
• is_eligible_checkout (required, boolean). Whether the product can be purchased directly inside ChatGPT. Requires is_eligible_search=true. Forces additional required fields downstream (seller_privacy_policy, seller_tos).
• is_eligible_ads (optional, boolean). Whether the product can appear in ChatGPT ads.

Gotcha: these are case-sensitive lower-case strings (true/false), not native booleans in the file-upload format. A capitalised True will fail validation.

Group 2: Basic product data

Five required fields and one optional. This is the absolute minimum for a recognisable product record.

• item_id (required, alphanumeric string, max 100). Unique merchant product ID per variant. Must remain stable over the product’s lifetime, changing item_id is treated as a new product, not an update.
• gtin (optional, numeric string, 8–14 digits). Universal product identifier. No dashes or spaces. If you have GTINs, supply them, they materially help disambiguation. Our GTIN validator covers GS1 check-digit validation in bulk.
• mpn (optional, alphanumeric, max 70). Manufacturer part number. Useful when GTINs aren’t available. Our MPN format validator catches common mistakes.
• title (required, UTF-8 string, max 150 chars). Product title. Avoid all-caps; ChatGPT result quality drops noticeably on shouty titles. Our product title character counter covers multi-channel length tests.
• description (required, UTF-8 string, max 5,000 chars). Plain text only, no HTML. Long descriptions are fine; padded descriptions are not.
• url (required, RFC 1738 URL). Product detail page. Must resolve with HTTP 200. HTTPS preferred. Our bulk image URL checker demonstrates the same pattern for image URLs and is adaptable to PDP URLs.

Gotcha: description rejects HTML. If your PIM stores descriptions as HTML, run them through an HTML-strip pass before publishing.

Group 3: Item information

The largest group, 14 fields covering physical and classification attributes. One is required (brand); most are optional but high-impact.

• brand (required, max 70). Product brand. Critical for ChatGPT to disambiguate.
• condition (optional, lower-case string). Product condition, typically new, used, refurbished.
• product_category (optional). Category taxonomy path with > separator (e.g., Apparel & Accessories > Shoes). Google taxonomy values work cleanly.
• material (optional, max 100). Primary material(s).
• dimensions (optional, LxWxH unit format). Overall dimensions. Units required if any dimension field is provided.
• length, width, height (optional). Individual dimensions. Provide all three if you use the individual-fields path.
• dimensions_unit (optional). Required if any dimension fields are provided (in, cm).
• weight (optional). Product weight. Requires item_weight_unit.
• item_weight_unit (optional). Weight unit (lb, kg). Required if weight is provided.
• age_group (optional, enum). One of newborn, infant, toddler, kids, adult.
• ads_metadata (optional, JSON object). String keys and values only.

Gotcha: the dimensions group is tightly coupled. Supplying length without dimensions_unit will fail. Either ship the bundled dimensions string or ship all three individual fields plus the unit.

Group 4: Media

Four fields, one required. ChatGPT result quality depends on usable images.

• image_url (required, RFC 1738 URL). Main product image. JPEG or PNG. HTTPS preferred.
• additional_image_urls (optional, comma-separated). Extra images.
• video_url (optional, URL). Publicly accessible video.
• model_3d_url (optional, URL). 3D model asset. GLB or GLTF preferred.

Gotcha: every URL in this group must be publicly resolvable. Auth-gated or session-gated images will silently degrade results.

Group 5: Price & promotions

Six fields, one required. Promotions data is API-only, file upload covers base price and sale price, but live promotional offers come through the API.

• price (required, number + ISO 4217 currency). Regular price.
• sale_price (optional, same format). Must be ≤ price.
• sale_price_start_date and sale_price_end_date (optional, ISO 8601). Sale window.
• unit_pricing_measure and base_measure (optional, paired). Unit price and base measure, both required together.
• pricing_trend (optional, max 80). Free-text price-trend signal (e.g., “lowest price in 90 days”).

Gotcha: prices must include currency in the value itself, in ISO 4217 format. A bare 29.99 will fail; 29.99 USD is the shape.

Group 6: Availability & inventory

Five fields, one required. The conditional rules here matter for pre-orders.

• availability (required, enum). One of in_stock, out_of_stock, pre_order, backorder, unknown.
• availability_date (conditional, ISO 8601). Required when availability=pre_order. Must be a future date.
• expiration_date (optional, ISO 8601). Remove product after this date.
• pickup_method (optional, enum). in_store, reserve, not_supported.
• pickup_sla (optional, number + duration). Pickup SLA. Requires pickup_method.

Group 7: Variants

Ten fields. Three are strongly recommended; the rest depend on category. Variants are where most ACP rejections come from, get them right.

• group_id (recommended). Shared identifier across all variants of a product.
• listing_has_variations (recommended, boolean string).
• variant_dict (recommended, JSON object). Map of variant attributes (e.g., {"colour": "navy", "size": "M"}).
• item_group_title (optional, max 150). Parent product title for grouped variants.
• color (optional, max 40). Variant colour.
• size (recommended for apparel, max 20). Variant size.
• size_system (recommended for apparel, ISO 3166 country code). Size system (e.g., US, GB).
• gender (optional, lower-case string).
• offer_id (optional). SKU + seller + price identifier.
• Custom variant fields (deprecated). Use variant_dict instead.

Gotcha: custom variant fields are deprecated. If your existing feed shape uses them, migrate to variant_dict before ACP onboarding.

Group 8: Fulfillment

Two fields, both optional but critical for checkout eligibility.

• shipping (optional). String in the format country:region:service_class:price:min_handling_days:max_handling_days:min_transit_days:max_transit_days. Omitting trailing fields is allowed.
• is_digital (optional, boolean string). Digital product flag.

Gotcha: the shipping string is positional. Get the order wrong and parsing fails silently. Validate against the spec’s example before bulk publishing.

Group 9: Merchant info

Five fields, three required for any product, two more required when checkout is enabled.

• seller_name (required, max 70). Seller name.
• marketplace_seller (optional, max 70). Marketplace seller of record for 3P sellers.
• seller_url (required, URL). Seller page. HTTPS preferred.
• seller_privacy_policy (conditional, URL). Required when is_eligible_checkout=true.
• seller_tos (conditional, URL). Required when is_eligible_checkout=true.

Gotcha: the privacy policy and ToS URLs must resolve. A 404 here is the most common ACP checkout-eligibility rejection.

Group 10: Returns

Four fields. One is required, three are optional but worth supplying.

• accepts_returns (optional, boolean string).
• return_deadline_in_days (optional, positive integer). Canonical return window. Use this, older synonyms have been deprecated.
• accepts_exchanges (optional, boolean string).
• return_policy (required, URL). Return policy URL. HTTPS preferred.

Group 11: Performance signals

Two fields, both optional. Both surface to ChatGPT as quality signals.

• popularity_score (optional, number). 0–5 scale or merchant-defined.
• return_rate (optional, percentage). 0–100%.

Supplying real values here helps ChatGPT rank your products against competitors with thinner data. Don’t fabricate, the model is good at detecting suspicious correlations.

Group 12: Compliance

Two fields, both recommended for checkout eligibility.

• warning / warning_url (recommended for checkout). Product disclaimers. If a URL, must resolve HTTP 200.
• age_restriction (recommended, positive integer). Minimum purchase age.

Regulated categories (alcohol, supplements, electronics with compliance markings) should always populate compliance fields.

Group 13: Reviews and Q&A

Six fields. None strictly required; all strongly recommended.

• review_count (optional, non-negative integer).
• star_rating (optional, 0–5).
• store_review_count (optional). Brand or store reviews.
• store_star_rating (optional, 0–5).
• q_and_a (recommended, list of objects). Each object has string q and string a fields.
• reviews (recommended, list of objects). Each review has title, content, minRating, maxRating, rating.

Gotcha: this is the most underused group. Merchants with structured review and FAQ data who expose it here meaningfully outperform competitors on ChatGPT result detail. If you have it, ship it.

Group 14: Related products

Two fields, both recommended.

• related_product_id (recommended, comma-separated list).
• relationship_type (recommended, enum). One of part_of_set, required_part, often_bought_with, substitute, different_brand, accessory.

Supplying these powers cross-sell and substitution suggestions inside ChatGPT.

Group 15: Geo tagging

Four fields. Two required, two optional but useful for multi-region merchants.

• target_countries (required, list). ISO 3166-1 alpha-2 codes. Only the first entry is used as the primary target country.
• store_country (required, ISO 3166-1 alpha-2). Store country.
• geo_price (optional, number + ISO 4217 currency). Region-specific price override.
• geo_availability (optional). Availability per region. ISO 3166 region codes only.

Required-field checklist

If you remember nothing else, remember these 15. Every product record needs them at minimum:

1. is_eligible_search
2. is_eligible_checkout
3. item_id
4. title
5. description
6. url
7. brand
8. image_url
9. price (with currency)
10. availability
11. seller_name
12. seller_url
13. return_policy
14. target_countries
15. store_country

Plus the conditionals: seller_privacy_policy and seller_tos when checkout is enabled, availability_date when pre-order, dimensions_unit/item_weight_unit when relevant dimensions or weights are supplied, pickup_sla when pickup_method is supplied, base_measure when unit_pricing_measure is supplied.

Validation gotchas to wire into your pipeline

These are the patterns most likely to bite you on first submission:

• Lower-case booleans. true/false, not True/TRUE.
• Currency embedded in price. 29.99 USD, not 29.99.
• ISO 8601 dates for sale_price_start_date, sale_price_end_date, availability_date, expiration_date.
• HTTPS-resolvable URLs for url, image_url, seller_url, seller_privacy_policy, seller_tos, return_policy, optional media URLs. 404s on these break eligibility.
• HTML stripped from description. Plain text only.
• Variant data in variant_dict, not legacy custom fields.
• All three dimension fields plus dimensions_unit when using individual-dimension fields.
• sale_price ≤ price, silent rejection if violated.
• ISO 3166 country codes for target_countries and store_country. Two-letter alpha-2.

A pre-publish validation step that enforces each of these will save you days of submission-and-rejection cycles. The same logic that powers Merchant Center pre-checks works here, see our product feed auditor for the universal pattern.

File upload, API, or both?

OpenAI’s recommended pattern is file upload plus API. The reasoning:

• File upload is your daily ground truth. It’s the easiest way to guarantee that the entire catalogue reaches OpenAI consistently each day, especially after bulk catalogue edits or category restructures.
• API is your intra-day update channel. It’s the only path for promotions data, and it’s how you push price changes, stock changes, or new product additions without waiting for the next daily snapshot.

A team running both has the cleanest operational model: file upload at a fixed time of day, API for everything that can’t wait until tomorrow.

What to do next

If you’re starting from scratch, ship a file-upload integration with the 15 required fields covered cleanly, then layer in conditionals, then layer in the optional fields that drive result quality (variants, reviews, Q&A, related products, performance signals). Stand up the API path once the daily file upload is stable.

For the broader strategy context, see agentic commerce shopping guide. For the cross-protocol view, see ACP vs UCP comparison and the agentic commerce acronym map. For Shopify-stack alignment, see Shopify Agents explained.

The feed spec is dry reading, but it’s the gate everything else passes through. Get it right once, and the harder work, checkout, payment, post-purchase, lands on a foundation that doesn’t crack under pressure.