1. Perché serve il Product Feed
Se lo confrontiamo con l’e‑commerce classico, il Product Feed è una via di mezzo tra:
- la «vetrina» dei prodotti (catalogo con prezzi, disponibilità, link e media);
- e un contratto tecnico che descrive quali SKU il merchant è disposto a mostrare e/o vendere tramite ChatGPT.
Nella sua specifica, OpenAI afferma chiaramente che il feed è la fonte unica di verità sui prodotti, su cui si basano ricerca, raccomandazioni e preparazione dei dati per il checkout.
In un negozio online tradizionale l’utente naviga tra le pagine, scorre le categorie, applica filtri ecc. Nell’AI‑commerce è l’opposto: l’utente dice semplicemente al modello «trovami un regalo digitale fino a 30 dollari per un amico sviluppatore che ama i giochi da tavolo» — e ChatGPT decide quali SKU del vostro Product Feed siano idonei, in che ordine mostrarli e come impaginarli come card fino all’Instant Checkout successivo.
Perciò il Product Feed risolve diverse esigenze insieme.
Primo, fornisce a ChatGPT dati strutturati per la ricerca. Il modello si basa non solo su titolo e descrizione, ma anche su categorie, tag, prezzo, disponibilità, locale, restrizioni per paese.
Secondo, è la fonte dei dati per il checkout. Quando ChatGPT inizia a preparare checkout_session, proprio dal feed prende ID SKU, prezzo, valuta, seller URL e altre informazioni commerciali.
Infine, il Product Feed è un contratto formalizzato tra voi e la piattaforma. Dichiarate esplicitamente: «ecco l’elenco degli SKU, ecco quali possono essere solo cercati (discovery) e quali possono anche essere acquistati tramite Instant Checkout».
Per visualizzarlo è comodo disegnare uno schema semplice.
flowchart TD A[GiftGenius DB] --> B[Feed Builder] B --> C["Product Feed (CSV/JSON/...)"] C --> D[OpenAI Ingestion] D --> E[Indice di ricerca + ranking] E --> F[ChatGPT/Agent seleziona i regali] F --> G["Instant Checkout (ACP)"]
A sinistra — il vostro database interno, dove vive già il catalogo «reale». A destra — ChatGPT, che viene mostrato all’utente. Al centro — il Product Feed e i meccanismi di ingestione e indicizzazione. Tutto quello che facciamo in questa lezione si trova esattamente tra A e D.
2. Formati e «fisica» del Product Feed
La specifica di OpenAI è piuttosto flessibile sul formato dei file: sono supportati TSV, CSV, XML e JSON. Questo è intenzionale, così la maggior parte dei sistemi esistenti (dai monoliti custom a Shopify) possono esportare il feed senza magie.
Tipicamente:
- pubblicate un file o un endpoint con il Product Feed sul vostro server HTTPS;
- registrate quell’indirizzo nel portale ChatGPT Merchants;
- OpenAI scarica periodicamente il feed, lo convalida e indicizza i prodotti.
La documentazione sottolinea che il feed va aggiornato regolarmente (anche ogni 10–15 minuti), così che gli utenti vedano prezzi e disponibilità aggiornati, soprattutto durante i saldi e i periodi di picco.
Nel nostro esempio didattico con GiftGenius useremo il formato JSON, perché risulta comodo agli sviluppatori TypeScript. Ma è importante capire che a livello di specifica OpenAI non è legato al JSON; è solo la scelta più pratica per noi.
Un feed JSON elementare potrebbe apparire così:
[
{
"id": "gg-coffee-sub-1m-usd",
"title": "Abbonamento al caffè per 1 mese",
"description": "Scatola mensile di caffè in grani per sviluppatori.",
"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
}
]Nella realtà i campi saranno di più: alcuni obbligatori, altri raccomandati o opzionali. Vediamo in seguito come funziona.
3. Prodotto vs variante (SKU): come modellarlo
Una delle domande più comuni: «Come rappresentare nel Product Feed taglie, bundle, durate dell’abbonamento e altre varianti di uno stesso prodotto?»
La specifica del Product Feed lavora con righe/record, ciascuno dei quali descrive una singola configurazione vendibile. Il pattern architetturale raccomandato dall’industria (e ben allineato al feed OpenAI) è il seguente: ogni singola configurazione (taglia, durata dell’abbonamento, piano, regione) è un record separato del feed, cioè uno SKU distinto.
Il prodotto base vive nel vostro modello interno, mentre nel feed operate a livello di SKU.
Per esempio, avete un servizio e abbonamenti da 1, 3, 6 mesi. Dal punto di vista del product feed sono SKU diversi. Se lo stesso servizio si può acquistare con 20 condizioni diverse, nel product feed dovrebbero esistere 20 SKU.
In TypeScript si può esprimere così:
// Modello interno di GiftGenius
export interface GiftProduct {
id: string; // product_123
name: string;
description: string;
baseImageUrl: string;
}
// SKU che andrà nel Product Feed
export interface GiftSkuFeedItem {
id: string; // product_123_usd_1m
productId: string; // riferimento a GiftProduct.id
title: string;
description: string;
price: number; // in unità minime (centesimi)
currency: string; // "usd"
}
All’interno di GiftGenius potete avere una relazione uno‑a‑molti tra GiftProduct e GiftSkuFeedItem. Nel feed, invece, restituite un elenco «piatto» di SKU.
Affinché ChatGPT possa capire quali SKU appartengono allo stesso prodotto base (per esempio, abbonamento da 1, 3 e 12 mesi), spesso si usa un campo di raggruppamento come item_group_id. Tuttavia è un pattern architetturale, non un requisito rigido dello standard.
Per esempio:
{
"id": "gg-coffee-sub-1m-usd", // SKU dell’abbonamento da 1 mese
"item_group_id": "gg-coffee-sub", // Il vostro prodotto
"title": "Abbonamento al caffè — 1 mese",
"price": 2900,
"currency": "usd",
"enable_search": true,
"enable_checkout": true
}E per l’abbonamento da 3 mesi:
{
"id": "gg-coffee-sub-3m-usd", // SKU dell’abbonamento da 3 mesi
"item_group_id": "gg-coffee-sub", // Lo stesso id del prodotto
"title": "Abbonamento al caffè — 3 mesi",
"price": 7900,
"currency": "usd",
"enable_search": true,
"enable_checkout": true
}Questo approccio facilita la vita sia al modello sia al vostro backend nella creazione degli ordini: l’ID dello SKU diventa la chiave univoca con cui potete sempre trovare l’esatta configurazione acquistata dall’utente.
4. Campi obbligatori del Product Feed e il loro impatto sull’UX
Nella specifica del Product Feed OpenAI divide i campi in tre gruppi: obbligatori (required), raccomandati (recommended) e opzionali (optional).
I nomi e gli elenchi precisi vanno sempre verificati nella documentazione aggiornata, ma a fini didattici possiamo rifarci a questo set «minimo».
| Campo | A cosa serve | Cosa succede se manca |
|---|---|---|
|
Identificatore univoco dello SKU all’interno del merchant | L’articolo non può essere identificato in modo univoco |
|
Titolo breve per la card | Più difficile per il modello capire di che articolo si tratta |
|
Descrizione estesa | Le risposte saranno più generiche, peggiore personalizzazione |
|
Prezzo in unità minime | Impossibile preparare il checkout |
|
Codice valuta ISO 4217, di solito in minuscolo | La piattaforma non saprà in quale valuta calcolare |
|
URL della pagina prodotto presso il merchant | L’utente non potrà raggiungere il vostro sito |
|
Stato di disponibilità (in_stock, out_of_stock ecc.) | Potrebbero essere mostrati articoli non disponibili |
|
Se l’articolo può essere usato nella ricerca | Senza true l’articolo non comparirà nei risultati |
|
Se può essere acquistato tramite Instant Checkout | Solo discovery/link‑out |
Un aspetto importante: enable_search e enable_checkout separano logicamente le modalità operative.
Se enable_search = true, enable_checkout = false, l’articolo può comparire nei risultati, ma al tentativo di acquisto l’utente verrà indirizzato al vostro link (link) sul vostro sito, e non sull’Instant Checkout dentro ChatGPT (dove la carta è già associata).
Se invece enable_checkout = true, allora, a parità delle altre condizioni (regione supportata, valuta, ACP backend valido), l’articolo può essere acquistato direttamente in ChatGPT con uno‑due clic (con un forte aumento della conversione).
Esempio di oggetto GiftGenius «minimamente idoneo» per il checkout:
{
"id": "gg-dev-notebook-plain-usd",
"title": "Taccuino minimalista per sviluppatori",
"description": "Nero, senza righe, 120 pagine. Per chi scrive le specifiche a mano.",
"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
}Notate: anche nell’esempio aggiungiamo l’immagine (image_link) — formalmente potrebbe essere un campo raccomandato e non obbligatorio, ma senza di essa l’UX peggiora molto.
5. Campi raccomandati e opzionali: come rendere il feed «appetibile»
I campi obbligatori servono «a far funzionare il tutto». Ma fermarsi lì equivale ad avere un CSV minimale per la contabilità, non una vetrina AI di qualità.
I campi raccomandati includono di solito:
- URL principale e aggiuntivi delle immagini;
- categoria del prodotto (spesso basata su una tassonomia, tipo «gifts > experiences > online courses»);
- brand/nome del merchant;
- attributi come colore, taglia, materiale;
- flag di contenuti per adulti, limiti d’età, ecc.
Più ricca è la descrizione del prodotto, più sensate saranno le risposte che il modello potrà generare. Per esempio, se indicate esplicitamente che il taccuino è fatto di carta riciclata e «supporta gli sviluppatori attenti al pianeta», ChatGPT potrà raccomandarlo consapevolmente a chi ha chiesto regali eco‑friendly.
In GiftGenius potremmo arricchire la descrizione di uno SKU del genere:
{
"id": "gg-dev-notebook-plain-usd",
"title": "Taccuino eco per sviluppatori",
"description": "Taccuino minimalista senza rigature, 120 pagine di carta riciclata.",
"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
}Attributi aggiuntivi come category e brand non solo migliorano i risultati, ma aiutano anche nell’analisi: potete vedere quali categorie convertono meglio tramite ChatGPT e quali peggio.
I campi opzionali sono spesso legati a scenari molto specifici (per esempio, parametri geografici del prezzo, di cui parleremo a parte, o metadati personalizzati). Vanno aggiunti man mano che il progetto matura, non «per riempire caselle».
6. Flag commerciali e modalità discovery‑only
Fissiamo ancora una volta la logica di enable_search e enable_checkout, perché è il ponte critico verso le prossime lezioni su ACP e Instant Checkout.
Immaginate di essere agli inizi come merchant su ChatGPT. Avete un catalogo di regali, ma ACP‑backend e Delegated Payment sono ancora in sviluppo. Volete già da ora che ChatGPT trovi i vostri SKU e indirizzi gli utenti al vostro sito per il pagamento.
In tal caso:
- pubblicate un Product Feed con enable_search = true per gli SKU desiderati;
- lasciate enable_checkout = false finché non avrete completato e certificato l’integrazione ACP.
ChatGPT potrà includere i vostri regali nelle risposte, mostrare le card e proporre un link «Vai al sito GiftGenius», ma non costruirà l’UI interna di Instant Checkout.
Quando implementate Agentic Checkout e Delegated Payment, potete passare certi prodotti alla modalità «pronti per Instant Checkout» — semplicemente impostando enable_checkout = true e soddisfacendo tutti i requisiti sui dati (prezzo, valuta, seller URL, ecc.).
A livello di specifiche, proprio i campi del Product Feed verranno usati per compilare line_items e l’importo in checkout_session.
In questo modo, il feed diventa una leva di fine tuning: quali SKU e in quale forma ChatGPT ha il diritto di vendere a vostro nome.
7. Locali, valute, regioni e prezzi multiregionali
Sapete bene che il mondo non si limita a en-US e ai dollari. Nei moduli sulla localizzazione abbiamo già discusso come locale e userLocation influiscano sulla logica di business. Qui diventano centrali: i prodotti in Germania possono costare diversamente rispetto agli USA, e alcuni regali non possono essere venduti in certi paesi.
La specifica del Product Feed lo contempla tramite diversi meccanismi.
Primo, la valuta: currency deve essere un codice ISO 4217 valido (ad es. usd, eur, gbp).
Secondo, si possono usare campi che descrivono prezzo e disponibilità dipendenti dalla geografia. La documentazione presenta esempi di attributi come geo_price e relativi codici regionali basati su ISO 3166.
Esistono due approcci architetturali di base.
Approccio uno: un feed per ogni regione.
- product-feed-us-en.json per gli USA;
- product-feed-de-de.json per la Germania;
- product-feed-br-pt.json per il Brasile.
In ciascun feed tutti gli SKU sono già allineati alla valuta e al locale desiderati. Semplicità per ChatGPT, più lavoro per voi nel mantenere feed multipli.
Approccio due: feed unico con campi geo.
All’interno di ogni record conservate o un array di prezzi, o attributi aggiuntivi:
{
"id": "gg-dev-notebook-multi",
"title": "Taccuino eco per sviluppatori",
"description": "Sostiene il tuo amore per il clean code e per il pianeta.",
"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
}La struttura concreta dei campi multiregionali dipende dalla versione della specifica, ma l’idea è una: il feed deve permettere alla piattaforma di capire in quali paesi lo SKU esiste e quanto costa lì.
Dal punto di vista di GiftGenius, è importante pensare al mapping tra:
- locale e userLocation noti a ChatGPT;
- e la parte del feed da cui prendere prezzi e testi.
Nei casi commerciali più comuni non restituite un singolo record «per tutto il mondo», ma create SKU diversi per paesi diversi, così da rispettare più facilmente tasse, policy e restrizioni sui prodotti.
8. Qualità dei dati e policy: senza queste l’Instant Checkout non decolla
Il Product Feed non riguarda solo il formato, ma anche la qualità dei dati e il rispetto delle policy di OpenAI.
Per la qualità OpenAI richiede esplicitamente:
- identificatori corretti e stabili;
- URL validi con HTTPS e codice di risposta 200;
- coerenza tra prezzo e valuta;
- disponibilità aggiornata (non devono risultare in_stock articoli che in realtà non lo sono più).
Inoltre nella specifica ci sono requisiti sulla lunghezza dei testi: ad esempio, title non deve essere troppo lungo (centinaia di caratteri), e description ha un limite ragionevole (migliaia di caratteri), affinché le card appaiano ordinate e non si trasformino in un romanzo in tre volumi.
Blocco a parte — la Prohibited Products Policy. È l’elenco di categorie di beni e servizi che non si possono vendere tramite Instant Checkout e/o ChatGPT in generale: cose ovvie come beni illegali, armi, alcuni servizi medici, ecc. I dettagli vanno sempre verificati nella policy aggiornata; per noi conta capire che il Product Feed verrà verificato non solo nel formato, ma anche nell’ammissibilità dei contenuti.
Se il vostro catalogo contiene categorie ambigue (per esempio, alcolici, gioco d’azzardo o prodotti legati ai minori), trattatele con particolare attenzione. Spesso è più semplice lasciarle in modalità enable_checkout = false e vendere solo tramite il vostro sito con tutta la copertura legale necessaria.
9. Pratica: componiamo un Product Feed minimo per GiftGenius
Applichiamo ora tutto questo in pratica e componiamo un feed semplice per tre SKU di GiftGenius. Supponiamo di avere:
- Taccuino eco per sviluppatori.
- Abbonamento al caffè per 1 mese.
- Buono regalo per il corso «TypeScript per adulti».
Per prima cosa definiamo il tipo TypeScript che useremo per generare il feed:
export interface GiftGeniusFeedItem {
id: string;
title: string;
description: string;
price: number; // in centesimi
currency: "usd" | "eur";
availability: "in_stock" | "out_of_stock";
link: string;
image_link?: string;
enable_search: boolean;
enable_checkout: boolean;
}Ora creiamo nel codice un array con alcuni elementi e poi lo serializziamo in JSON:
export const giftGeniusFeed: GiftGeniusFeedItem[] = [
{
id: "gg-eco-notebook-usd",
title: "Taccuino eco per sviluppatori",
description: "Taccuino minimalista senza rigature di carta riciclata.",
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: "Abbonamento al caffè per sviluppatori — 1 mese",
description: "Scatola mensile di caffè in grani. Compatibile con le scadenze.",
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: "Buono regalo per il corso TypeScript",
description: "Corso online per sviluppatori che finalmente vogliono capire i 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 // per ora solo discovery
}
];Si può poi creare una semplice utility che ogni N minuti generi il file product-feed.json da questa struttura e lo pubblichi sul vostro server HTTPS.
import { writeFile } from "node:fs/promises";
import { giftGeniusFeed } from "./feed-data";
// Generatore semplicissimo di feed JSON
async function buildProductFeed() {
const json = JSON.stringify(giftGeniusFeed, null, 2);
await writeFile("public/product-feed.json", json, "utf8");
}
buildProductFeed().catch(console.error);È chiaro che in un progetto reale non conserverete l’intero feed nel codice; i dati verranno invece presi dal DB. Ma per iniziare è utile mettere insieme almeno un esempio didattico del genere, per testare la pipeline: generazione → pubblicazione → validazione.
10. Anti‑esempio: com’è un Product Feed «scarso»
Per comprendere meglio i requisiti della specifica e dell’UX, è utile vedere un esempio di feed che formalmente quasi funziona, ma in pratica porterà a problemi:
{
"id": "1",
"title": "Regalo",
"description": "Regalo fantastico",
"price": 12.333333,
"currency": "usdollars",
"availability": "yes",
"link": "http://giftgenius.local/gift/1",
"enable_search": "true",
"enable_checkout": "maybe"
}Qui si possono contare subito diversi problemi.
Primo, id = "1" — identificatore povero e instabile. Se un giorno migrate il DB o introducete sharding, tali identificatori diventano fragili. Meglio usare ID significativi e abbastanza lunghi, unici entro il merchant.
Secondo, price è indicato come numero decimale con coda infinita. Specifiche e sistemi di pagamento si aspettano il prezzo in unità minime (centesimi) come intero, per evitare problemi di floating point e arrotondamenti.
Terzo, currency = "usdollars" e availability = "yes" non rispettano i formati attesi (ISO 4217 e l’elenco di stati consentiti).
Quarto, link punta a http e a un dominio locale — entrambi inaccettabili in produzione; la specifica richiede esplicitamente HTTPS e accessibilità pubblica.
Quinto, i flag enable_search e enable_checkout devono essere booleani, non stringhe. Altrimenti il parser OpenAI o non accetterà il feed, o applicherà un valore di default che potrebbe sorprendere in modo spiacevole.
Questi problemi possono portare sia a un errore di validazione duro (feed rifiutato), sia a situazioni peggiori: feed formalmente accettato, ma parte degli SKU ignorata o funzionante in modo diverso dal previsto. Ecco perché conviene investire in una validazione interna già dalla vostra parte.
11. Errori tipici lavorando con il Product Feed
Errore n°1: pensare al feed come a un «CSV una tantum» per l’import.
A volte i team vedono il Product Feed come un file che generano «per l’integrazione» e poi dimenticano. Nell’AI‑commerce non è così: il feed è una fonte di verità viva, che va aggiornata regolarmente. Se cambiate prezzi, togliete prodotti dalla vendita, lanciate promozioni — tutto deve finire nel feed in tempo. Altrimenti ChatGPT raccomanderà ciò che non esiste più o a prezzi vecchi, e gli utenti avranno motivo di irritarsi.
Errore n°2: mescolare modello di prodotto e SKU.
Un anti‑pattern comune è cercare di rappresentare un prodotto base con molte opzioni in un unico record del feed, con campi tipo «size1/size2/size3» o «duration1/duration2». Il modello non capisce cosa sia effettivamente in vendita e il vostro ACP‑backend soffre a spacchettare quei campi al checkout. Molto più semplice e affidabile: uno SKU — un record del feed, anche se è una variante dello stesso prodotto.
Errore n°3: ignorare locali e regioni.
Gli sviluppatori del primo MVP spesso impostano currency = "usd" e enable_checkout = true ovunque, senza considerare che l’Instant Checkout nel vostro Paese potrebbe non essere disponibile o che determinati prodotti non si possano vendere in alcuni Stati per policy o legge. Quando poi entrate in un nuovo mercato, tutto inizia a rompersi: prezzi che non tornano, tasse non considerate. Meglio da subito vincolare gli SKU a regioni e valute, anche se al momento avete un solo mercato.
Errore n°4: trattare le descrizioni come vecchi testi SEO.
Alcuni team copiano nel Product Feed descrizioni datate dei loro siti, talvolta scritte per «parole chiave» e bot. Per ChatGPT è più dannoso che utile: il modello sa già scrivere testi; gli servono soprattutto fatti strutturati, onesti e accurati. Meglio essere concisi e puntuali che riempire description di marketing prolisso.
Errore n°5: non validare il feed in autonomia.
Affidarsi solo alla validazione di OpenAI è la ricetta per notti insonni prima delle scadenze. Implementate un validatore semplice sul vostro backend o in CI, che controlli schemi dei campi, valori ammessi, formati di URL e valute. Si può fare anche in TypeScript, usando per esempio Zod o check ad hoc. Così intercetterete i problemi prima di caricare il feed in produzione.
Errore n°6: includere «di tutto e di più» nel Product Feed.
La tentazione è inserire migliaia di SKU «tanto per», nel caso servissero. In pratica complica debug, analytics e controllo qualità. È più ragionevole partire da un sottoinsieme limitato: solo le categorie e gli SKU che siete pronti a curare e che volete davvero vendere tramite ChatGPT. Il resto può stare in modalità discovery o restare fuori dall’integrazione.
Errore n°7: non sincronizzare Product Feed e ACP‑backend.
Feed e ACP‑API sono due facce della stessa medaglia. Se nel feed compare un nuovo SKU, ma il vostro backend non sa ancora venderlo (o viceversa, lo rimuovete dal feed ma il backend crede ancora che esista), avrete desincronizzazione, bug difficili e ticket complessi per il supporto. Buona pratica: avere un unico modello di dominio del catalogo e usarlo sia per generare il feed sia per gestire il checkout.
GO TO FULL VERSION