OpenAI product feed spec: every field explained

Q: What are the required fields in an OpenAI product feed?

Nine: item_id, title, description, url, brand, seller_name, image_url, availability and price.

OpenAI's Stable product feed spec has nine required fields: item_id, title, description, url, brand, seller_name, image_url, availability and price. Feeds go by SFTP as Parquet, jsonl.gz, csv.gz or tsv.gz — a full snapshot at least daily — or through the API. The Draft spec is for planning only.

All fields at a glance

Requirement levels below are the spec's own: required, optional, conditionally required, and fields that only count once an integration or market is set up. The spec has no "recommended" tier.

Field	Level	What it holds
`item_id`	Required	Item or variant ID; unique and stable
`title`	Required	Name plus variant; ≤150 characters
`description`	Required	Plain-text facts; ≤5,000 characters
`url`	Required	Public product page (http/https)
`brand`	Required	Brand; no placeholders
`seller_name`	Required	The seller supplying the item, on every row
`image_url`	Required	Main variant image, JPEG or PNG
`availability`	Required	`in_stock` · `out_of_stock` · `pre_order` · `backorder` · `unknown`
`price`	Required	Regular price as amount + ISO currency, e.g. `79.99 USD`
`group_id`	Conditional	Parent listing ID for variants; must differ from every `item_id`
`listing_has_variations`	Conditional	`true` on variant rows
`variant_dict`	Conditional	Selected options, e.g. `{"color":"Black"}`
`is_eligible_search`	Optional	Search eligibility; default true, set false to delist
`gtin`	Optional	8/12/13/14 digits with a valid check digit
`mpn`	Optional	Manufacturer part number, with `brand`
`condition`	Optional	`new` · `refurbished` · `used`
`product_category`	Optional	Category path separated by `>`
`material` / `color` / `size`	Optional	Materials and the selected color and size
`gender` / `age_group`	Optional	`male` · `female` · `unisex` / `newborn` · `infant` · `toddler` · `kids` · `adult`
`dimensions`	Optional	At least two axes plus `unit` (in, cm, ft, m, mm)
`weight` + `item_weight_unit`	Optional	Net weight in g, kg, oz or lb
`additional_image_urls`	Optional	Extra images
`sale_price`	Optional	Lower than `price`, same currency
`shipping_price`	Optional	Shipping charge; omitted means unknown
`accepts_returns` / `return_deadline_in_days` / `return_policy`	Optional	Returns accepted, window in days, policy URL
`review_count` / `star_rating`	Optional	Product reviews; rating 0–5 with two decimals
`shipping` / `size_system` / `store_review_count` / `store_star_rating` / `accepts_exchanges` / `is_digital`	Needs setup	Accepted only once the related integration is set up
`target_countries` / `store_country`	Market setup	Standard uploads: `["US"]` and US
`is_ads_eligible` / `ads_metadata`	Conditional	Opt-in for the separate ads program
`is_eligible_checkout` / `seller_privacy_policy` / `seller_tos`	Conditional	Only with an enabled checkout integration

The spec also accepts legacy aliases (id, sku, item_group_id, enable_search, return_window…), and some of them override the current names. Send the current names only.

Price, availability and variants

Price: amount, a space, then an ISO 4217 code — 79.99 USD, no thousands separators. Update it when a sale starts or ends; date fields don't schedule changes.
Availability: an invalid or missing value rejects the row.
Variants: one row per variant. Rows share a group_id but each has its own price, stock and image, plus listing_has_variations=true and a variant_dict.
Naming differs from Google: OpenAI uses pre_order and group_id; Google Merchant Center uses preorder and item_group_id.

Formats, size and updates

Formats: Parquet (preferred), jsonl.gz, csv.gz or tsv.gz, UTF-8.
Delivery: SFTP file or API; promotions are API-only. OpenAI suggests a daily full file plus API updates.
Size: shards of up to 500,000 items and about 500 MB each, under stable filenames.
Removals: items dropped from a snapshot are kept for up to 14 days; send is_eligible_search=false to delist.
First upload: OpenAI suggests starting with a sample of about 100 items.

OpenAI's own pages disagree in places: one page says feeds are CSV or JSON, and the best-practices page uses Draft field names. Follow the Stable spec page.

Questions

What are the required fields in an OpenAI product feed?

Nine: item_id, title, description, url, brand, seller_name, image_url, availability and price.

Can I send an XML feed?

The file-upload spec lists Parquet, jsonl.gz, csv.gz and tsv.gz, not XML. Convert a Google Merchant XML feed and rename fields such as item_group_id → group_id and preorder → pre_order.

How often should the feed update?

A full snapshot at least daily, plus updates when price or stock changes.

Should I use the Draft spec?

No. OpenAI marks Draft as not for production; use Stable.