OpenAI Feed Spesifikasyonları: Product Feed Alanları, File Upload ve API Yapısı

OpenAI product feed spec, ürün verilerinin ChatGPT içindeki alışveriş, ürün keşfi ve reklam deneyimlerinde doğru şekilde işlenebilmesi için gereken teknik veri yapısını tanımlar. Bu yapı; ürün başlığı, açıklaması, fiyatı, stok bilgisi, görselleri, varyantları, satıcı bilgileri ve uygunluk alanları gibi birçok alanı içerir.

OpenAI dokümanlarında ürün feed’i için iki temel aktarım yöntemi bulunur: File Upload ve API. File Upload yöntemi, tam katalog dosyasının SFTP üzerinden gönderilmesine dayanır. API yöntemi ise product feed oluşturma, feed metadata alma ve ürünleri API üzerinden güncelleme süreçleri için kullanılır.

OpenAI Product Feed Hangi Yöntemlerle Yüklenebilir?

Yöntem	Kullanım amacı	Güncelleme mantığı	Teknik yapı
File Upload	Tam ürün kataloğunu OpenAI’ye dosya olarak göndermek	Full snapshot	SFTP üzerinden dosya gönderimi
API	Feed oluşturmak, feed metadata almak ve ürünleri API ile güncellemek	Product upsert / partial update	REST API endpoint’leri

File Upload yöntemi tam katalog yüklenmesi olarak düşünülebilir ve OpenAI bu yapıyı source of truth kabul edilen full snapshot feed modeli olarak tanımlar. API yöntemi ise feed oluşturma, mevcut feed bilgisini alma ve ürün güncellemelerini API üzerinden yapma amaçlarıyla kullanılır.

File Upload feed gereksinimleri

OpenAI file upload dokümanına göre ürün feed’i SFTP üzerinden OpenAI’ye gönderilir. Format tarafında parquet önerilir; ayrıca jsonl.gz, csv.gz ve tsv.gz formatları da desteklenir. Feed UTF-8 encoding kullanmalı ve dosya adı her güncellemede sabit tutulmalıdır.

Konu	OpenAI gereksinimi
Delivery model	Feed’ler OpenAI’ye SFTP üzerinden push edilir.
Feed modeli	Full snapshot feed
Önerilen güncelleme sıklığı	En az günlük
Önerilen format	`parquet`, tercihen compression ile
Desteklenen diğer formatlar	`jsonl.gz`, `csv.gz`, `tsv.gz`
Encoding	UTF-8
Dosya adı	Stabil dosya adı kullanılmalı ve her güncellemede aynı dosya yolu/adı overwrite edilmelidir.
Shard kullanımı	Shard set sabit tutulmalı ve aynı shard dosyaları güncellenmelidir.
Shard boyutu	Shard başına 500.000 ürüne kadar önerilir; shard dosyalarının yaklaşık 500 MB altında tutulması hedeflenmelidir.

Full snapshot mantığı

File Upload yönteminde OpenAI feed’i tam katalog snapshot’ı olarak ele alır. Bu nedenle her güncelleme, katalogdaki güncel ürün durumunu yansıtmalıdır.

Senaryo	Uygulama
Ürün katalogda kalmaya devam edecek	Ürün kaydı full snapshot içinde gönderilir.
Ürün ChatGPT Search içinde görünmemeli	`is_eligible_search=false` gönderilir.
Ürün tamamen kaldırılmalı	Ürün bir sonraki full snapshot’tan çıkarılır.
Feed validasyonu yapılacak	Önce yaklaşık 100 ürünlük sample ile başlanabilir.
İlk full snapshot	Required field’lar tüm satırlarda kontrol edilmelidir.

OpenAI Product Feed'de En Çok Karşılaşılan Ingestion Hataları

Hata türü	Açıklama
Eksik required field	Zorunlu alanların bazı ürünlerde boş veya eksik olması.
Spec dışı field adı	OpenAI product feed spec içinde yer almayan veya eski field isimlerinin kullanılması.
Malformed field value	Fiyat, stok, URL, tarih veya boolean gibi alanların beklenen formatta gönderilmemesi.
Stabil olmayan ID	`item_id` değerinin zaman içinde değişmesi.
Erişilemeyen URL	Ürün URL’i veya görsel URL’inin HTTP 200 dönmemesi.

File Upload ürün schema yapısı

OpenAI file upload product spec, flat-file schema olarak tanımlanır. Stable schema production file upload entegrasyonları için desteklenen yoldur.

Schema bölümü	İçerik
OpenAI Flags	ChatGPT Search, checkout ve ads eligibility alanları
Basic Product Data	Ürün ID, başlık, açıklama, URL
Item Information	Marka, kategori, materyal, ölçü, ağırlık, yaş grubu
Media	Ana görsel, ek görseller, video, 3D model
Price & Promotions	Fiyat, indirimli fiyat, kampanya tarihleri
Availability & Inventory	Stok durumu, preorder tarihi, expiration date
Variants	Grup ID, renk, beden, varyant sözlüğü
Fulfillment	Shipping ve dijital ürün bilgisi
Merchant Info	Seller adı, seller URL, policy URL’leri
Returns	İade ve değişim bilgileri
Performance Signals	Popülerlik ve iade oranı
Compliance	Uyarılar ve yaş kısıtları
Reviews and Q&A	Review count, star rating, store rating

OpenAI Flags alanları

OpenAI Flags alanları, ürünün ChatGPT Search, checkout veya ads süreçlerinde kullanılıp kullanılmayacağını kontrol eder.

Alan	Tip	Desteklenen değerler	Zorunluluk	Açıklama
`is_eligible_search`	Boolean	`true`, `false`	Required	Ürünün ChatGPT Search sonuçlarında gösterilip gösterilmeyeceğini belirler.
`is_eligible_checkout`	Boolean	`true`, `false`	Required	Ürünün ChatGPT içinde doğrudan satın alma için uygun olup olmadığını belirtir.
`is_ads_eligible`	Boolean	`true`, `false`	Ads için required; non-Ads feed için optional	Ürünün ChatGPT Ads için işlenip işlenmeyeceğini belirler.

OpenAI Product Feed Basic Product Data Alanları

Basic Product Data bölümü, ürünün temel kimliğini ve ürün detay sayfasına yönlendirme bilgisini içerir. item_id, title, description ve url alanları file upload schema içinde required olarak yer alır.

Alan	Tip	Zorunluluk	Kural / Not
`item_id`	String	Required	Merchant product ID; varyant bazında unique olmalı, stabil kalmalı, max 100 karakter.
`gtin`	String	Optional	GTIN, UPC veya ISBN; 8-14 digit; tire veya boşluk kullanılmamalı.
`mpn`	String	Optional	Manufacturer part number; max 70 karakter.
`title`	String	Required	Product title; max 150 karakter; all-caps kullanılmamalı.
`description`	String	Required	Plain text product description; max 5.000 karakter.
`url`	URL	Required	Product detail page URL; HTTP 200 dönmeli, HTTPS önerilir.

Item Information alanları

Alan	Tip	Zorunluluk	Kural / Not
`brand`	String	Required	Product brand; max 70 karakter.
`condition`	String	Optional	Örnek: `new`; lower-case string.
`product_category`	String	Optional	Kategori yolu; `>` separator önerilir.
`material`	String	Optional	Ana materyal; max 100 karakter.
`dimensions`	String	Optional	`LxWxH unit` formatı.
`length`, `width`, `height`	String	Optional	Tekil ölçü alanları birlikte kullanılmalı.
`dimensions_unit`	String	Koşullu	`length`, `width` veya `height` varsa gerekli.
`weight`	String	Optional	Ürün ağırlığı.
`item_weight_unit`	String	Koşullu	`weight` varsa gerekli.
`age_group`	Enum	Optional	`newborn`, `infant`, `toddler`, `kids`, `adult`
`ads_metadata`	Object	Optional	Ads metadata için string key-value JSON object.

Media alanları

Media bölümü, ürünün ana görselini ve ek medya varlıklarını içerir. File upload schema’da image_url required olarak belirtilir.

Alan	Tip	Zorunluluk	Kural / Not
`image_url`	URL	Required	Ana ürün görseli; JPEG/PNG; HTTPS önerilir.
`additional_image_urls`	String	Optional	Virgülle ayrılmış ek görsel URL listesi.
`video_url`	URL	Optional	Public erişilebilir olmalı.
`model_3d_url`	URL	Optional	GLB/GLTF önerilir.

Price & Promotions alanları

Price & Promotions bölümü, standart fiyat, indirimli fiyat ve kampanya tarihleri için kullanılır. price alanı required olarak belirtilir ve currency code içermelidir.

Alan	Tip	Zorunluluk	Kural / Not
`price`	Number + currency	Required	Örnek: `79.99 USD`; currency code içermeli.
`sale_price`	Number + currency	Optional	`price` değerinden küçük veya eşit olmalı.
`sale_price_start_date`	Date	Optional	ISO 8601 formatı.
`sale_price_end_date`	Date	Optional	ISO 8601 formatı.
`unit_pricing_measure / base_measure`	Number + unit	Optional	İki alan birlikte kullanılmalı.
`pricing_trend`	String	Optional	Max 80 karakter.

Availability & Inventory alanları

Availability & Inventory bölümü, ürünün stok ve satın alınabilirlik durumunu tanımlar. availability required alanıdır ve lower-case enum değerleriyle gönderilmelidir.

Alan	Tip	Desteklenen değerler	Zorunluluk	Kural / Not
`availability`	Enum	`in_stock`, `out_of_stock`, `pre_order`, `backorder`, `unknown`	Required	Lower-case string.
`availability_date`	Date	ISO 8601	Pre-order için required	Gelecek tarih olmalı.
`expiration_date`	Date	ISO 8601	Optional	Gelecek tarih olmalı.
`pickup_method`	Enum	`in_store`, `reserve`, `not_supported`	Optional	Lower-case string.
`pickup_sla`	Number + duration	Örnek: `1 day`	Koşullu	`pickup_method` varsa kullanılabilir.

Variants alanları

Variants bölümü, aynı ürünün renk, beden veya farklı özelliklere göre varyantlarını tanımlamak için kullanılır.

Alan	Tip	Zorunluluk	Kural / Not
`group_id`	String	Recommended	Varyantlar arasında ortak grup ID.
`listing_has_variations`	Boolean	Recommended	`true` veya `false`.
`variant_dict`	Object	Recommended	Örnek: `{"color":"Blue","size":"10"}`
`item_group_title`	String	Optional	Grup ürün başlığı; max 150 karakter.
`color`	String	Optional	Max 40 karakter.
`size`	String	Apparel için recommended	Max 20 karakter.
`size_system`	Country code	Apparel için recommended	ISO 3166 2 harfli ülke kodu.
`gender`	String	Optional	Lower-case string.
`offer_id`	String	Optional	Feed içinde unique olmalı.

Fulfillment alanları

Alan	Tip	Zorunluluk	Format / Not
`shipping`	String	Optional	`country:region:service_class:price:min_handling_days:max_handling_days:min_transit_days:max_transit_days`
`is_digital`	Boolean	Optional	`true` veya `false`.

Merchant Info alanları

Merchant Info bölümü seller bilgisi, seller URL’i ve policy URL’leri için kullanılır.

Alan	Tip	Zorunluluk	Kural / Not
`seller_name`	String	Required / Display	Max 70 karakter.
`marketplace_seller`	String	Optional	Marketplace seller of record.
`seller_url`	URL	Required	HTTPS önerilir.
`seller_privacy_policy`	URL	Checkout için koşullu	`is_eligible_checkout=true` ise required olabilir.
`seller_tos`	URL	Checkout için koşullu	`is_eligible_checkout=true` ise required olabilir.

Returns, review ve compliance alanları

Bölüm	Alan	Zorunluluk	Not
Returns	`accepts_returns`	Optional	`true` veya `false`.
Returns	`return_deadline_in_days`	Optional	Pozitif integer.
Returns	`accepts_exchanges`	Optional	`true` veya `false`.
Returns	`return_policy`	Required	HTTPS önerilir.
Performance Signals	`popularity_score`	Optional	0-5 scale veya merchant-defined.
Performance Signals	`return_rate`	Optional	0-100%.
Compliance	`warning / warning_url`	Recommended for Checkout	URL varsa HTTP 200 dönmeli.
Compliance	`age_restriction`	Recommended	Pozitif integer.
Reviews	`review_count`	Optional	Non-negative integer.
Reviews	`star_rating`	Optional	0-5 scale.
Reviews	`store_review_count`	Optional	Non-negative integer.
Reviews	`store_star_rating`	Optional	0-5 scale.

API feed yapısı

OpenAI API feed yapısı, product feed oluşturma ve feed metadata alma işlemleri için Feeds endpoint’lerini kullanır. API dokümanında GET /product_feeds/{id} endpoint’i feed metadata döndürür; POST /product_feeds ise yeni product feed oluşturur.

Endpoint	Method	Amaç
`/product_feeds/{id}`	GET	Belirli bir feed için metadata döndürür.
`/product_feeds`	POST	Yeni product feed oluşturur.

GET /product_feeds/{id}

Alan	Tip	Required	Açıklama
`id`	string	Yes	Product feed identifier.

Response içinde id, target_country ve updated_at alanları dönebilir. target_country, ISO 3166 iki harfli ülke kodudur.

POST /product_feeds

Alan	Tip	Required	Açıklama
`target_country`	string	No	ISO 3166 iki harfli ülke kodu.

Response içinde feed id, target_country ve updated_at alanları yer alır. Geçersiz payload durumunda 400 Bad Request dönebilir.

API Products endpoint’leri

Products API, belirli bir feed içindeki ürünleri almak veya ürün güncellemelerini upsert etmek için kullanılır. PATCH /product_feeds/{id}/products endpoint’i ürünleri id alanına göre eşleştirir. Request içinde gönderilmeyen ürünler değişmeden kalır.

Endpoint	Method	Amaç
`/product_feeds/{id}/products`	GET	Feed içindeki ürünleri döndürür.
`/product_feeds/{id}/products`	PATCH	Ürünleri upsert eder.

PATCH /product_feeds/{id}/products

Alan	Tip	Required	Açıklama
`id`	string	Yes	Feed identifier.
`target_country`	string	No	ISO 3166 iki harfli ülke kodu.
`products`	Product[]	Yes	Product feed için ürün array’i.

Response içinde id ve accepted alanları döner. Payload geçersizse 400 Bad Request, feed bulunamazsa 404 Not Found dönebilir.

API Product schema

API product schema, file upload flat-file yapısından farklı olarak nested product ve variant objeleriyle çalışır. Product seviyesinde id ve variants required olarak görünür; variant seviyesinde ise id ve title required alanlardır.

Product object

Alan	Tip	Required	Açıklama
`id`	string	Yes	Stable global product identifier.
`title`	string	No	Product title.
`description`	Description	No	Product description content.
`url`	string (uri)	No	Canonical product URL.
`media`	Media[]	No	Product-level media assets.
`variants`	Variant[]	Yes	Product variants.

Variant object

Alan	Tip	Required	Açıklama
`id`	string	Yes	Stable global variant identifier.
`title`	string	Yes	Variant title.
`description`	Description	No	Variant description content.
`url`	string (uri)	No	Variant URL.
`barcodes`	Barcode[]	No	Variant barcode values.
`price`	Price	No	Active sale price.
`list_price`	Price	No	Discount öncesi referans fiyat.
`unit_price`	UnitPrice	No	Unit pricing metadata.
`availability`	Availability	No	Variant availability.
`categories`	Category[]	No	Variant categories.
`condition`	Condition	No	Item condition.
`variant_options`	VariantOption[]	No	Örnek: color, size.
`media`	Media[]	No	İlk media primary kabul edilir.
`seller`	Seller	No	Seller metadata.

API alt objeleri

API product schema içinde Description, Availability, Price, Media, VariantOption, Category, Seller ve Link gibi alt objeler bulunur.

Obje	Alan	Required	Açıklama
Description	`plain`	No	Plain-text description.
Description	`html`	No	HTML description.
Description	`markdown`	No	Markdown description.
Availability	`available`	No	Variant satın alınabilir mi?
Availability	`status`	No	`in_stock`, `backorder`, `preorder`, `out_of_stock`, `discontinued`
Price	`amount`	Yes	ISO 4217 minor units.
Price	`currency`	Yes	Üç harfli currency code.
Media	`type`	Yes	Media type.
Media	`url`	Yes	Media URL.
Media	`alt_text`	No	Alternate text.
VariantOption	`name`	Yes	Örnek: color veya size.
VariantOption	`value`	Yes	Seçilen option değeri.
Category	`value`	Yes	Category label veya path.
Category	`taxonomy`	No	Örnek: `google_product_category`, `shopify`, `merchant`.
Seller	`name`	No	Seller name.
Seller	`links`	No	Seller-related links.
Link	`type`	Yes	`privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`
Link	`url`	Yes	Link destination URL.

File Upload ve API schema farkı

Konu	File Upload	API
Veri modeli	Flat-file schema	Nested JSON object
Teslimat	SFTP	REST API
Güncelleme	Full snapshot	Upsert / partial product changes
Ürün ID alanı	`item_id`	Product `id`, Variant `id`
Varyant yapısı	Flat alanlar: `group_id`, `variant_dict`, `color`, `size`	`variants[]` array ve `variant_options[]`
Fiyat	`79.99 USD` gibi number + currency string	Minor units + currency object
Açıklama	Plain text string	`plain`, `html` veya `markdown`
Görsel	`image_url`, `additional_image_urls`	`media[]`
Kategori	`product_category`	`categories[]` + taxonomy
Güncelleme etkisi	Snapshot kaynak kabul edilir.	Gönderilmeyen ürünler değişmeden kalır.

Minimum teknik kontrol listesi

Kontrol	Beklenen durum
Feed yöntemi seçildi mi?	File Upload veya API
File Upload kullanılıyorsa SFTP hazır mı?	Evet
Dosya formatı destekleniyor mu?	`parquet`, `jsonl.gz`, `csv.gz`, `tsv.gz`
Encoding doğru mu?	UTF-8
Dosya adı sabit mi?	Evet
Required alanlar tüm ürünlerde var mı?	Evet
`item_id` veya API `id` alanları stabil mi?	Evet
Product URL HTTP 200 dönüyor mu?	Evet
Ana görsel URL’i erişilebilir mi?	Evet
Fiyat currency code içeriyor mu?	Evet
Stok değerleri supported enum ile uyumlu mu?	Evet
Ads için ürünler `is_ads_eligible=true` mı?	Gerekli ürünlerde evet
Varyantlı ürünlerde grup ve varyant alanları dolu mu?	Evet
Seller ve return policy alanları var mı?	Evet
Test sample validasyonundan geçildi mi?	Evet

OpenAI Product Feed Spec için kaynak dokümanlar

Doküman	Kapsam	URL
File Upload Overview	SFTP, full snapshot, dosya formatı ve delivery gereksinimleri	OpenAI File Upload Overview
File Upload Products	Flat-file product schema ve field tanımları	OpenAI File Upload Product Spec
API Overview	Commerce API genel yapısı	OpenAI Commerce API Overview
API Feeds	Product feed oluşturma ve metadata alma endpoint’leri	OpenAI API Feeds
API Products	Product retrieve ve upsert endpoint’leri	OpenAI API Products

Optifeed notu

OpenAI product feed spec, hem teknik field uyumluluğu hem de ürün verisinin güncelliği açısından düzenli kontrol gerektirir. Optifeed, e-ticaret markalarının ürün başlığı, açıklama, fiyat, stok, varyant, kategori, görsel ve metadata alanlarını farklı reklam ve AI shopping kanallarına uygun şekilde yönetmesine yardımcı olur.

OpenAI feed hazırlığına başlamadan önce product feed’in AI shopping içindeki rolünü daha geniş açıdan değerlendirmek için Product Feed ve AI Shopping ve AI Shopping Ready Product Feed Nasıl Hazırlanır? içeriklerini inceleyebilirsiniz.