Product Feed: призначення, модель даних, ключові поля та політики

1. Навіщо взагалі потрібен Product Feed

Якщо порівнювати з класичною e-commerce, Product Feed — це щось середнє між:

• «вітриною» товарів (каталогом із цінами, наявністю, посиланнями та медіа);
• і технічним контрактом, який описує, які саме SKU продавець готовий показувати та/або продавати через ChatGPT.

OpenAI у своїй специфікації прямо зазначає, що feed — це єдине джерело правди про товари. Саме на нього спираються пошук, рекомендації та підготовка даних для оформлення замовлення.

У звичайному інтернет-магазині користувач сам переходить між сторінками: гортає категорії, застосовує фільтри тощо. В AI-комерції все навпаки. Користувач просто каже моделі: «Підібери мені цифровий подарунок до 30 доларів другові-розробнику, який любить настільні ігри», — а ChatGPT уже сам визначає, які саме SKU з вашого Product Feed підходять, у якому порядку їх показати та як усе це оформити у вигляді карток і подальшого Instant Checkout.

Тому Product Feed розвʼязує одразу кілька завдань.

По-перше, він дає ChatGPT структуровані дані для пошуку. Модель спирається не лише на опис і назву товару, а й на категорії, теги, ціну, доступність, локаль, а також обмеження за країнами.

По-друге, він є джерелом даних для оформлення замовлення. Коли ChatGPT починає готувати checkout_session, саме з фіду беруться ID SKU, ціна, валюта, seller URL та інша комерційна інформація.

І нарешті Product Feed — це формалізований контракт між вами та платформою. Ви прямо кажете: «Ось список SKU; ось які з них можна просто шукати (discovery), а які — ще й оформлювати через Instant Checkout».

Щоб це побачити, зручно намалювати просту схему.

flowchart TD
  A[GiftGenius DB] --> B[Feed Builder]
  B --> C["Product Feed (CSV/JSON/...)"]
  C --> D[OpenAI Ingestion]
  D --> E[Пошуковий індекс + ранжування]
  E --> F[ChatGPT/Agent підбирає подарунки]
  F --> G["Instant Checkout (ACP)"]

Ліворуч — ваша внутрішня база, у якій уже живе «справжній» каталог. Праворуч — ChatGPT, якого бачить користувач. Посередині — Product Feed і механізми його приймання та індексування. Усе, що ми робимо в цій лекції, розташоване рівно між A і D.

2. Формати та «фізика» Product Feed

Специфікація OpenAI доволі гнучка щодо формату файлів: підтримуються TSV, CSV, XML і JSON. Так зроблено спеціально, щоб більшість наявних систем (від самописних монолітів до Shopify) могли експортувати фід без зайвих «ритуалів».

У типовому варіанті:

• ви розміщуєте файл або ендпойнт із Product Feed на своєму HTTPS-сервері;
• цю адресу реєструєте в порталі ChatGPT Merchants;
• OpenAI періодично завантажує цей фід, валідує та індексує товари.

Документація підкреслює, що фід потрібно оновлювати регулярно (можна навіть кожні 10–15 хвилин), щоб користувачі бачили актуальні ціни та наявність, особливо під час розпродажів і в пікові періоди.

У навчальному прикладі з GiftGenius ми працюватимемо з форматом JSON, бо він добре «заходить» TypeScript-розробникам. Але важливо розуміти: на рівні специфікації OpenAI не привʼязаний до JSON. Просто для нас так зручніше.

Найпростіший JSON-фід міг би виглядати так:

[
  {
    "id": "gg-coffee-sub-1m-usd",
    "title": "Підписка на каву на 1 місяць",
    "description": "Щомісячна коробка зернової кави для розробника.",
    "price": 2900,
    "currency": "usd",
    "availability": "in_stock",
    "link": "https://giftgenius.app/gifts/coffee-subscription-1m",
    "image_link": "https://cdn.giftgenius.app/images/coffee-1m.png",
    "enable_search": true,
    "enable_checkout": true
  }
]

У реальності полів буде більше: деякі з них обовʼязкові, інші — рекомендовані або опціональні. Як це влаштовано, розберемося далі.

3. Продукт vs варіант (SKU): як це моделювати

Одне з найчастіших запитань: «А як у Product Feed відобразити розміри, пакети, тривалості підписки й інші варіанти одного товару?»

Специфікація Product Feed оперує рядками/записами, кожен із яких описує одну конфігурацію, що продається. Архітектурний патерн, який рекомендує індустрія (і який добре стикується з OpenAI-фідом), виглядає так: кожна окрема конфігурація (розмір, варіант підписки, тариф, регіон) — це окремий запис фіду, тобто окремий SKU.

Базовий продукт живе у вашій внутрішній моделі, а у фіді ви працюєте на рівні SKU.

Наприклад, у вас є сервіс і підписки на нього на 1 місяць, 3 місяці, 6 місяців. З погляду Product Feed це різні SKU. Якщо один сервіс можна купити на 20 різних умовах, то у вашому Product Feed має бути 20 SKU.

У TypeScript це можна виразити приблизно так:

// Домашня модель GiftGenius
export interface GiftProduct {
  id: string;              // product_123
  name: string;
  description: string;
  baseImageUrl: string;
}

// SKU, який піде в Product Feed
export interface GiftSkuFeedItem {
  id: string;              // product_123_usd_1m
  productId: string;       // посилання на GiftProduct.id
  title: string;
  description: string;
  price: number;           // у мінімальних одиницях (центах)
  currency: string;        // "usd"
}

Усередині GiftGenius у вас може бути звʼязок один-до-багатьох між GiftProduct і GiftSkuFeedItem. А у фіді ви віддаєте вже «плоский» список SKU.

Щоб ChatGPT міг розуміти, які SKU належать до одного базового продукту (наприклад, підписка на 1, 3 і 12 місяців), часто використовують групувальне поле на кшталт item_group_id. Утім, це радше архітектурний патерн, а не жорстка вимога стандарту.

Наприклад:

{
  "id": "gg-coffee-sub-1m-usd",                // SKU підписки на 1 місяць
  "item_group_id": "gg-coffee-sub",            // Ваш продукт
  "title": "Підписка на каву — 1 місяць",
  "price": 2900,
  "currency": "usd",
  "enable_search": true,
  "enable_checkout": true
}

А для 3-місячної підписки:

{
  "id": "gg-coffee-sub-3m-usd",                // SKU підписки на 3 місяці
  "item_group_id": "gg-coffee-sub",            // Той самий id‑продукта
  "title": "Підписка на каву — 3 місяці",
  "price": 7900,
  "currency": "usd",
  "enable_search": true,
  "enable_checkout": true
}

Такий підхід полегшує життя і моделі, і вашому бекенду під час створення замовлень: ID SKU стає унікальним ключем, за яким ви завжди можете знайти точну конфігурацію, яку купив користувач.

4. Обовʼязкові поля Product Feed та їхній вплив на UX

У специфікації Product Feed OpenAI ділить поля приблизно на три групи: обовʼязкові (required), рекомендовані (recommended) та опціональні (optional).

Конкретні назви й списки завжди потрібно звіряти з актуальною документацією. Але для навчальних цілей можна спиратися на такий «мінімальний» набір.

id

title

description

price

currency

link

availability

enable_search

enable_checkout

Важливий нюанс: enable_search і enable_checkout логічно розділяють режими роботи.

Якщо enable_search = true, enable_checkout = false, товар може брати участь у результатах пошуку. Але під час спроби купити користувач перейде за вашим посиланням (link) на ваш сайт, а не в Instant Checkout у ChatGPT (де вже привʼязана картка).

Якщо ж enable_checkout = true, то за виконання інших умов (підтримуваний регіон, валюта, валідний ACP backend) товар можна купити прямо в ChatGPT за один-два кліки. А це суттєво підвищує конверсію.

Приклад «мінімально придатного» обʼєкта GiftGenius для checkout:

{
  "id": "gg-dev-notebook-plain-usd",
  "title": "Мінімалістичний блокнот для розробника",
  "description": "Чорний, без ліній, 120 сторінок. Для тих, хто пише специфікації від руки.",
  "price": 1500,
  "currency": "usd",
  "availability": "in_stock",
  "link": "https://giftgenius.app/gifts/dev-notebook",
  "image_link": "https://cdn.giftgenius.app/images/dev-notebook.png",
  "enable_search": true,
  "enable_checkout": true
}

Зверніть увагу: навіть у прикладі ми додаємо зображення (image_link). Формально це поле може бути рекомендованим, а не обовʼязковим. Але без нього UX буде значно гіршим.

5. Рекомендовані та опціональні поля: як зробити фід «смачнішим»

Обовʼязкові поля — це «щоб узагалі працювало». Але якщо зупинитися лише на них, ви отримаєте щось на кшталт мінімально валідного CSV для бухгалтерії, а не якісну AI-вітрину.

Рекомендовані поля зазвичай охоплюють:

• основний і додаткові URL зображень;
• категорію товару (часто на основі таксономії, на зразок «gifts > experiences > online courses»);
• бренд/merchant-name;
• атрибути на кшталт кольору, розміру, матеріалу;
• прапорці adult-контенту, вікові обмеження тощо.

Чим повніше ви опишете товар, тим змістовніші відповіді зможе генерувати модель. Наприклад, якщо ви прямо зазначите, що блокнот зроблено з переробленого паперу й він пасує «розробникам, яким не байдуже довкілля», ChatGPT зможе свідомо рекомендувати його користувачеві, який просив еко-дружні подарунки.

У GiftGenius ми могли б розширити опис такого SKU:

{
  "id": "gg-dev-notebook-plain-usd",
  "title": "Еко-блокнот для розробника",
  "description": "Мінімалістичний блокнот без ліновки, 120 сторінок із переробленого паперу.",
  "price": 1500,
  "currency": "usd",
  "availability": "in_stock",
  "link": "https://giftgenius.app/gifts/eco-dev-notebook",
  "image_link": "https://cdn.giftgenius.app/images/eco-dev-notebook.png",
  "category": "gifts > office > notebooks",
  "brand": "GiftGenius Originals",
  "enable_search": true,
  "enable_checkout": true
}

Додаткові атрибути на кшталт category і brand не лише покращують результати, а й допомагають в аналітиці: ви можете дивитися, які категорії краще конвертують через ChatGPT, а які — гірше.

Опціональні поля часто повʼязані з дуже специфічними сценаріями (наприклад, геопараметрами ціни, про які поговоримо окремо, або кастомними метаданими). Їх варто додавати в міру «дорослішання» проєкту, а не «для галочки».

6. Комерційні прапорці та режим discovery-only

Зафіксуймо ще раз чітку логіку enable_search і enable_checkout, бо це критичний місток до наступних лекцій про ACP та Instant Checkout.

Уявімо, що ви лише починаєте шлях як продавець у ChatGPT. У вас є каталог подарунків, але ACP-backend і Delegated Payment ще в розробці. Ви хочете вже зараз, щоб ChatGPT міг знаходити ваші SKU і відправляти користувачів на ваш сайт для оплати.

У цьому випадку ви:

• публікуєте Product Feed з enable_search = true для потрібних SKU;
• залишаєте enable_checkout = false доти, доки не «обгорнете» й не сертифікуєте ACP-інтеграцію.

Тоді ChatGPT зможе включати ваші подарунки у відповіді для користувачів, показувати картки та пропонувати посилання «Перейти на сайт GiftGenius», але не будуватиме внутрішній UI Instant Checkout.

Коли ж ви реалізуєте Agentic Checkout і Delegated Payment, певні товари можна перевести в режим «готові для Instant Checkout». Для цього достатньо встановити enable_checkout = true і додатково виконати всі вимоги до даних (наявність ціни, валюти, seller URL тощо).

На рівні специфікацій саме поля з Product Feed використовуватимуться для заповнення полів line_items і суми в checkout_session.

Отже, фід стає важелем тонкого налаштування: які саме SKU і в якому вигляді ChatGPT узагалі має право продавати від вашого імені.

7. Локалі, валюти, регіони та мульти-регіональні ціни

Гадаю, ви знаєте, що світ не обмежується en-US і доларами. У модулях про локалізацію ми вже обговорювали, як locale і userLocation впливають на бізнес-логіку. Тут це виходить на перший план: товари в Німеччині можуть коштувати інакше, ніж у США, а деякі подарунки взагалі не можна продавати в окремих країнах.

Специфікація Product Feed враховує це через кілька механізмів.

По-перше, валюта: currency має бути валідним кодом ISO 4217 (наприклад, usd, eur, gbp).

По-друге, можуть використовуватися поля, що описують геозалежну ціну та доступність. У документації наводиться приклад атрибутів на кшталт geo_price і повʼязаних із ним регіональних кодів, заснованих на ISO 3166.

Є два базові архітектурні підходи.

Підхід перший: один фід на один регіон.

• product-feed-us-en.json для США;
• product-feed-de-de.json для Німеччини;
• product-feed-br-pt.json для Бразилії.

У кожному фіді всі SKU вже приведені до потрібної валюти та локалі. Для ChatGPT це простіше, але вам доведеться підтримувати кілька фідів.

Підхід другий: єдиний фід із geo-полями.

Усередині кожного запису ви зберігаєте або масив цін, або додаткові атрибути:

{
  "id": "gg-dev-notebook-multi",
  "title": "Еко-блокнот для розробника",
  "description": "Підтримує вашу любов до чистого коду і до планети.",
  "prices": [
    { "region": "US", "currency": "usd", "price": 1500 },
    { "region": "DE", "currency": "eur", "price": 1400 }
  ],
  "availability_by_region": [
    { "region": "US", "availability": "in_stock" },
    { "region": "DE", "availability": "out_of_stock" }
  ],
  "enable_search": true,
  "enable_checkout": true
}

Конкретна структура мульти-регіональних полів залежить від версії специфікації, але ідея одна: фід має дозволяти платформі зрозуміти, у яких країнах SKU існує і скільки він там коштує.

З погляду GiftGenius важливо продумати зіставлення між:

• locale і userLocation, які ChatGPT знає;
• і тією частиною фіду, з якої потрібно брати ціни та тексти.

Найчастіше в комерційних сценаріях ви не віддаєте один запис «на весь світ», а робите різні SKU для різних країн. Так простіше дотримуватися податків, політик і обмежень на товари.

8. Якість даних і політики: без цього Instant Checkout не запрацює

Product Feed — це не лише про формат, а й про якість даних і дотримання політик OpenAI.

У частині якості OpenAI прямо вимагає:

• коректні, стабільні ідентифікатори;
• валідні URL з HTTPS і кодом відповіді 200;
• узгодженість ціни та валюти;
• актуальну наявність (не повинно бути in_stock товарів, яких насправді вже немає).

Також у специфікації є вимоги до довжини текстів. Наприклад, title не має бути надто довгим (сотні символів), а description має розумний ліміт (тисячі символів), щоб картки виглядали охайно й не перетворювалися на роман у трьох томах.

Окремий блок — Prohibited Products Policy. Це перелік категорій товарів і послуг, які не можна продавати через Instant Checkout і/або ChatGPT узагалі: очевидні речі на кшталт незаконних товарів, зброї, деяких медичних послуг тощо. Деталі завжди потрібно перевіряти в актуальній політиці, але для нас важливо усвідомити: Product Feed перевірятимуть не лише на формат, а й на допустимість змісту.

Якщо ваш каталог містить неоднозначні категорії (наприклад, алкоголь, азартні ігри або щось, повʼязане з дітьми), до цих розділів варто ставитися з особливою увагою. Часто їх простіше залишити в режимі enable_checkout = false і продавати лише через власний сайт із повноцінною юридичною обвʼязкою.

9. Практика: збираємо мінімальний Product Feed для GiftGenius

Тепер застосуймо все це на практиці й зберімо простий фід для трьох SKU GiftGenius. Уявімо, що в нас є:

1. Еко-блокнот для розробника.
2. Підписка на каву на 1 місяць.
3. Подарунковий сертифікат на курс «TypeScript для дорослих».

Спочатку опишемо TypeScript-тип, який використовуватимемо для генерації фіду:

export interface GiftGeniusFeedItem {
  id: string;
  title: string;
  description: string;
  price: number;         // у центах
  currency: "usd" | "eur";
  availability: "in_stock" | "out_of_stock";
  link: string;
  image_link?: string;
  enable_search: boolean;
  enable_checkout: boolean;
}

Тепер створимо в коді масив із кількома елементами, а потім серіалізуємо його в JSON:

export const giftGeniusFeed: GiftGeniusFeedItem[] = [
  {
    id: "gg-eco-notebook-usd",
    title: "Еко-блокнот для розробника",
    description: "Мінімалістичний блокнот без ліновки із переробленого паперу.",
    price: 1500,
    currency: "usd",
    availability: "in_stock",
    link: "https://giftgenius.app/gifts/eco-dev-notebook",
    image_link: "https://cdn.giftgenius.app/images/eco-dev-notebook.png",
    enable_search: true,
    enable_checkout: true
  },
  {
    id: "gg-coffee-sub-1m-usd",
    title: "Підписка на каву для розробника — 1 місяць",
    description: "Щомісячна коробка зернової кави. Сумісна з дедлайнами.",
    price: 2900,
    currency: "usd",
    availability: "in_stock",
    link: "https://giftgenius.app/gifts/coffee-subscription-1m",
    image_link: "https://cdn.giftgenius.app/images/coffee-1m.png",
    enable_search: true,
    enable_checkout: true
  },
  {
    id: "gg-ts-course-gift-usd",
    title: "Подарунковий сертифікат на курс TypeScript",
    description: "Онлайн-курс для розробників, які нарешті хочуть зрозуміти generics.",
    price: 9900,
    currency: "usd",
    availability: "in_stock",
    link: "https://giftgenius.app/gifts/ts-course",
    image_link: "https://cdn.giftgenius.app/images/ts-course.png",
    enable_search: true,
    enable_checkout: false // поки лише discovery
  }
];

Далі можна зробити просту утиліту, яка раз на N хвилин генеруватиме файл product-feed.json із цієї структури та викладатиме його на ваш HTTPS-сервер.

import { writeFile } from "node:fs/promises";
import { giftGeniusFeed } from "./feed-data";

// Найпростіший генератор JSON-фіда
async function buildProductFeed() {
  const json = JSON.stringify(giftGeniusFeed, null, 2);
  await writeFile("public/product-feed.json", json, "utf8");
}

buildProductFeed().catch(console.error);

Зрозуміло, що в реальному проєкті ви не зберігатимете весь фід у коді — натомість дані братимуться з БД. Але на старті корисно зібрати хоча б такий навчальний приклад, щоб протестувати пайплайн: генерація → викладка → валідація.

10. Антиприклад: як виглядає «поганий» Product Feed

Щоб краще відчути вимоги специфікації та UX, корисно подивитися на приклад фіду, який формально майже працює, але на практиці призведе до проблем:

{
  "id": "1",
  "title": "Подарунок",
  "description": "Класний подарунок",
  "price": 12.333333,
  "currency": "usdollars",
  "availability": "yes",
  "link": "http://giftgenius.local/gift/1",
  "enable_search": "true",
  "enable_checkout": "maybe"
}

Тут можна одразу нарахувати кілька проблем.

По-перше, id = "1" — нестабільний і «бідний» ідентифікатор. Якщо ви колись мігруєте БД або введете шардування, такі ідентифікатори стануть крихкими. Краще використовувати осмислені й достатньо довгі ID, унікальні в межах продавця.

По-друге, price задано як десяткове число з «нескінченним хвостом». Специфікації та платіжні системи зазвичай очікують ціну в мінімальних одиницях (центи, копійки) цілим числом, щоб уникнути проблем із плаваючою точкою та округленням.

По-третє, currency = "usdollars" і availability = "yes" не відповідають очікуваним форматам (ISO 4217 і перелік допустимих статусів).

По-четверте, link веде на http і локальний домен — ні те, ні інше неприйнятне для реального продакшену. Специфікація прямо вимагає HTTPS і публічної доступності.

По-пʼяте, прапорці enable_search і enable_checkout мають бути булевими значеннями, а не рядками. Інакше парсер OpenAI або не прийме фід, або приведе все до значення за замовчуванням — і це може неприємно здивувати.

Такі проблеми можуть призвести як до жорсткої помилки валідації (фід відхилено), так і до неприємнішої ситуації: фід формально прийнято, але частину SKU проігноровано або вони працюють не так, як ви очікуєте. Саме тому варто інвестувати у внутрішню валідацію ще з вашого боку.

11. Типові помилки під час роботи з Product Feed

Помилка №1: думати про фід як про «разовий CSV» для імпорту.
Іноді команди сприймають Product Feed як файл, який вони один раз згенерують «для інтеграції» — і забудуть. В AI-комерції це не так: фід — живе джерело правди, яке має регулярно оновлюватися. Якщо ви змінюєте ціни, знімаєте товари з продажу, запускаєте промоакції — усе це має вчасно потрапляти у фід. Інакше ChatGPT рекомендуватиме те, чого вже немає, або за старою ціною. Користувачі цілком справедливо будуть незадоволені.

Помилка №2: змішувати модель продукту та SKU.
Поширений антипатерн — намагатися описати один базовий продукт із купою опцій в одному записі фіду, додаючи безліч полів на кшталт «size1/size2/size3» або «duration1/duration2». У результаті модель не розуміє, що саме продається, а ваш ACP-бекенд починає страждати від «розпакування» цих полів у момент чекауту. Набагато простіше й надійніше: один SKU — один запис фіду, навіть якщо це варіант у межах одного продукту.

Помилка №3: ігнорувати локалі та регіони.
Розробники, які роблять перший MVP, часто ставлять currency = "usd" і enable_checkout = true для всього підряд, не замислюючись про те, що Instant Checkout у вашому регіоні може бути недоступним або що деякі товари не можна продавати в окремих країнах — через політику чи закон. Потім, коли ви виходите на новий ринок, усе починає ламатися: ціни не сходяться, податки не враховуються. Краще від самого початку привʼязувати SKU до регіонів і валют, навіть якщо у вас поки що лише один ринок.

Помилка №4: ставитися до описів як до SEO-текстів із минулого.
Частина команд копіює у Product Feed старі описи зі своїх сайтів — іноді написані під «ключові слова» та роботів. Для ChatGPT це радше шкідливо, ніж корисно: модель і так уміє писати текст, їй набагато важливіші структуровані, чесні та точні факти. Краще описувати стисло й по суті, ніж забивати description маркетинговою «водою» на пів екрана.

Помилка №5: не валідувати фід самостійно.
Покладатися лише на валідацію з боку OpenAI — шлях до болючих ночей перед дедлайнами. Варто зробити простий валідатор на своєму бекенді або в CI, який перевіряє схеми полів, допустимі значення, формати URL і валют. Це можна зробити навіть на TypeScript, використовуючи, наприклад, Zod або власні перевірки. Тоді ви ловитимете проблеми ще до того, як заллєте фід у продакшен.

Помилка №6: включати до Product Feed «усе підряд».
Іноді хочеться одразу додати у фід тисячі SKU: мовляв, «нехай будуть — раптом знадобляться». На практиці це ускладнює і налагодження, і аналітику, і контроль якості. Набагато розумніше почати з обмеженої підмножини: лише ті категорії та SKU, за якими ви готові стежити й які справді хочете продавати через ChatGPT. Решту можна тримати в discovery-режимі або взагалі обійтися без інтеграції.

Помилка №7: не синхронізувати Product Feed і ACP-бекенд.
Фід і ACP API — дві сторони однієї медалі. Якщо у фіді зʼявився новий SKU, а ваш бекенд ще не вміє його продавати (або навпаки: SKU прибрали з фіду, але бекенд усе ще «вірить», що він існує), ви отримаєте розсинхронізацію, складні баги та непрості запити в підтримку. Гарний тон — мати єдину доменну модель каталогу й використовувати її і для генерації фіду, і для обробки чекауту.