Products

Feed Reference

Start with the required product fields and a minimal example. Optional fields describe variants, product attributes, shipping, and returns. Ads product feeds follow the Ads product feeds guide. Checkout requires a separately enabled integration.

Start with discovery

Submit one row per purchasable item or variant. Include the nine required fields in Basic product data, then add the optional data that describes your products. Ads and checkout have separate requirements.

• Basic product data and minimal example
• Identity and variants
• Product attributes, images, and prices
• Shipping, returns, and reviews
• Markets, Ads, and checkout
• Google-compatible feeds

Value conventions

These tables describe what to submit. Required fields must contain a value; conditional requirements apply only to the stated use case. Format guidance is not a guarantee that every invalid value will be rejected at upload.

For optional fields, omit an unknown value. Unless a row says otherwise, an omitted field, JSON null, or an empty delimited cell supplies no value. Do not use placeholder strings such as null, unknown, or n/a; unknown is valid only where explicitly listed. An empty value does not mean zero or false. For boolean fields, use JSON true or false, or the lowercase strings true and false in delimited files. These values are not valid for other field types.

Use UTF-8 text and absolute HTTP or HTTPS URLs; prefer HTTPS. Product and image URLs must be publicly accessible. Keep identifiers as strings to preserve leading zeros. In CSV, quote a cell containing commas, quotes, or newlines, and double each embedded quote. JSON objects in CSV or TSV cells must be serialized as JSON. Use the file upload guide for delivery.

{"item_id":"MUG-350-BLUE","title":"Blue ceramic mug, 350 mL","description":"Dishwasher-safe glazed ceramic mug with a handle.","url":"https://example.com/products/mug-blue","brand":"Northline","seller_name":"Northline Home","image_url":"https://example.com/images/mug-blue.jpg","price":"18.00 USD","availability":"in_stock"}

{
  "item_id": "TRAIL-BLK-10",
  "group_id": "TRAIL",
  "listing_has_variations": true,
  "variant_dict": {
    "color": "Black",
    "size": "10"
  },
  "offer_id": "northline-TRAIL-BLK-10",
  "title": "Trail running shoes — black, size 10",
  "description": "Waterproof trail shoes with a rubber outsole.",
  "url": "https://example.com/products/trail?color=black&size=10",
  "brand": "Northline",
  "seller_name": "Northline Outdoor",
  "image_url": "https://example.com/images/trail-black.jpg",
  "price": "79.99 USD",
  "availability": "in_stock"
}

{
  "item_id": "TRAIL-BLK-11",
  "group_id": "TRAIL",
  "listing_has_variations": true,
  "variant_dict": {
    "color": "Black",
    "size": "11"
  },
  "offer_id": "northline-TRAIL-BLK-11",
  "title": "Trail running shoes — black, size 11",
  "description": "Waterproof trail shoes with a rubber outsole.",
  "url": "https://example.com/products/trail?color=black&size=11",
  "brand": "Northline",
  "seller_name": "Northline Outdoor",
  "image_url": "https://example.com/images/trail-black.jpg",
  "price": "79.99 USD",
  "availability": "out_of_stock"
}

Ads

Ads feeds use the product data in this reference plus the Ads product feeds guide. These fields are not required for discovery.

Google-compatible Ads feeds use registered eligibility settings and supported Google columns; uploaded OpenAI eligibility controls do not override them.

Checkout

Checkout requires a separately enabled integration. Setting an eligibility flag does not complete checkout onboarding. Continue to provide accurate discovery data and configure digital-item support when applicable.

Compatibility notes

Existing Custom_variant1_category / Custom_variant1_option pairs, and the corresponding 2 and 3 pairs, remain accepted along with lowercase aliases. Migrate each pair to one entry in variant_dict, with the category as the key and the selected option as the value. An explicit variant_dict takes precedence. Do not mix representations; an explicit empty map does not fall back to the legacy pairs.

Existing aliases remain accepted: id or sku for item_id, item_group_id for group_id, enable_search for is_eligible_search, enable_checkout for is_eligible_checkout, is_eligible_ads for is_ads_eligible, and return_window for return_deadline_in_days. Send only one name per value: item_id wins over id and sku; group_id wins over item_group_id; the enable_ flags win over their is_eligible_ names; is_ads_eligible wins over its alias; and return_window wins over return_deadline_in_days.

Sale-window dates, expiration dates, and availability dates do not schedule price or availability changes in this contract. Update current prices and availability in your feed when they change. Do not rely on uploaded dates to remove a product or display a pre-order date. Warning and age-restriction fields do not establish purchase restrictions.

Google-compatible product data feeds

Use this format only after OpenAI confirms it for your registered feed. Upload a UTF-8, tab-delimited .txt or .tsv file, or a comma-delimited .csv file. Gzip-compressed .txt.gz, .txt.gzip, .tsv.gz, and .csv.gz files are supported. Use one header row and one product or variant per row. JSON, spreadsheets, XML, RSS, and Atom are not supported by this compatibility path.

Use lowercase, underscore-separated column names. .txt files also accept common display labels such as image link. Do not use g:-prefixed XML names. For additional context, see Google’s product data specification; only the profile described here is supported by OpenAI.

Required columns and format selection

Include nonempty id, title, description, link, image_link, availability, price, and brand on every row. Their types and meanings match item_id, title, description, url, image_url, availability, price, and brand in this reference, with these differences:

• title is limited to 150 characters and description to 5,000. Use plain text.
• link and image_link must be HTTP or HTTPS URLs without a username or password.
• availability must be in_stock, out_of_stock, preorder, or backorder. Use preorder, not the OpenAI spelling pre_order; unknown is not accepted.
• price requires a decimal amount and three-letter currency code. It must be positive except for the mobile-subscription case described below. Amounts are normalized to two decimal places; submit prices at that precision to avoid rounding.
• The conditional identifier and availability-date requirements in the next table also apply.

Register a merchant display name that is nonempty and not a placeholder such as unknown, null, or n/a. OpenAI uses that registered name as the seller identity on every row. An uploaded seller_name cannot override it. The seller URL is derived from the product link’s scheme and host.

OpenAI checks the OpenAI format first, then this compatibility profile, using samples from each nonempty file. A match requires an accepted sample from every file that supplies records. One format applies to the entire upload, not to individual rows. A file accepted as OpenAI format retains OpenAI field semantics; filename extensions alone do not select Google-compatible behavior. Confirm the selected format during setup, especially before relying on eligibility controls.

Optional and conditional columns

The value conventions in the main reference apply: omit unknown optional data, keep identifiers as strings, and use CSV quoting for commas and embedded quotes. An empty optional cell means no value unless the table specifies a default. Only identifier_exists accepts a boolean in this table; false is not an empty value for any other field.

For a zero-price item, google_product_category must identify a supported mobile device using category ID 267 (mobile phones) or 4745 (tablets). Category paths do not qualify for this exception. Supply a valid subscription_cost. Other zero-price products are rejected.

Eligibility and markets

Accepted Google-compatible products have search enabled and checkout disabled. Uploaded is_eligible_search=false or enable_search=false does not opt a product out on this path. Upload only products intended for discovery. To use per-item search controls, use a feed confirmed to follow the OpenAI format.

For Ads feeds, eligibility comes from registered feed settings; uploaded OpenAI eligibility fields do not override them. Supported Ads filter columns include custom_label_0 through custom_label_4: optional strings, such as summer, with an empty value meaning no label. Confirm the configured filter columns with your Ads integration.

If OpenAI confirms market-specific processing, registered target countries replace uploaded country values and a price currency outside the configured currencies is rejected. Otherwise, the target remains US. Uploaded seller, checkout, return-policy, and Ads control columns do not add those capabilities.

Legacy item_group_title, video_link, and virtual_model_link metadata may be accepted from existing feeds; they are not used for product discovery. New feeds can omit them. Keep current price and availability up to date even when you send date metadata.

Upload History reports missing required columns and invalid supported values. A malformed row can be rejected while valid rows continue processing.