1. Por que precisamos de um Product Feed
Se compararmos com o e‑commerce clássico, o Product Feed é algo entre:
- a “vitrine” de produtos (catálogo com preços, disponibilidade, links e mídia);
- e um contrato técnico que descreve quais SKUs exatamente o merchant está disposto a exibir e/ou vender pelo ChatGPT.
A OpenAI, em sua especificação, afirma explicitamente que o feed é a fonte única da verdade sobre os produtos, na qual se baseiam a busca, as recomendações e a preparação dos dados para o checkout.
Em uma loja on‑line tradicional, o usuário navega por páginas, percorre categorias, aplica filtros etc. No AI‑commerce é o contrário: o usuário apenas diz ao modelo “escolha um presente digital de até 30 dólares para um amigo desenvolvedor que gosta de jogos de tabuleiro” — e o ChatGPT decide quais SKUs do seu Product Feed são adequados, em que ordem mostrá‑los e como apresentar tudo em forma de cartões e do subsequente Instant Checkout.
Por isso, o Product Feed resolve várias tarefas de uma só vez.
Em primeiro lugar, ele fornece ao ChatGPT dados estruturados para busca. O modelo se baseia não apenas no título e na descrição, mas também em categorias, tags, preço, disponibilidade, locale, restrições por país.
Em segundo lugar, ele é a fonte de dados para o checkout. Quando o ChatGPT começa a preparar a checkout_session, é do feed que vêm o ID do SKU, preço, moeda, seller URL e outras informações comerciais.
Por fim, o Product Feed é um contrato formalizado entre você e a plataforma. Você declara explicitamente: “aqui está a lista de SKUs; estes podem ser usados apenas para discovery, e estes também podem ser vendidos via Instant Checkout”.
Para visualizar isso, é útil desenhar um esquema simples.
flowchart TD A[GiftGenius DB] --> B[Feed Builder] B --> C["Product Feed (CSV/JSON/...)"] C --> D[OpenAI Ingestion] D --> E[Índice de pesquisa + ranqueamento] E --> F[ChatGPT/Agent seleciona presentes] F --> G["Instant Checkout (ACP)"]
À esquerda — seu banco interno, onde vive o catálogo “real”. À direita — o ChatGPT, que é exibido ao usuário. No meio — o Product Feed e os mecanismos de ingestão e indexação. Tudo o que fazemos nesta aula está exatamente entre A e D.
2. Formatos e “física” do Product Feed
A especificação da OpenAI é bastante flexível quanto ao formato dos arquivos: TSV, CSV, XML e JSON são suportados. Isso foi feito propositalmente para que a maioria dos sistemas existentes (de monólitos caseiros a Shopify) possa exportar o feed sem malabarismos.
No cenário típico:
- você hospeda um arquivo ou endpoint com o Product Feed no seu servidor HTTPS;
- registra esse endereço no portal ChatGPT Merchants;
- a OpenAI busca esse feed periodicamente, valida e indexa os produtos.
A documentação ressalta que o feed precisa ser atualizado regularmente (até a cada 10–15 minutos), para que os usuários vejam preços e disponibilidade atualizados, especialmente em promoções e períodos de pico.
No exemplo didático com o GiftGenius, trabalharemos com o formato JSON, porque é bastante familiar para desenvolvedores TypeScript. Mas é importante entender: no nível da especificação, a OpenAI não está presa ao JSON; ele é apenas o mais conveniente para nós.
Um feed JSON mais simples seria assim:
[
{
"id": "gg-coffee-sub-1m-usd",
"title": "Assinatura de café por 1 mês",
"description": "Caixa mensal de café em grãos para um desenvolvedor.",
"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
}
]Na prática, haverá mais campos; alguns deles são obrigatórios, outros recomendados ou opcionais. Vamos entender isso adiante.
3. Produto vs variante (SKU): como modelar
Uma das perguntas mais frequentes: “Como refletir em um Product Feed tamanhos, pacotes, durações de assinatura e outras variantes de um único produto?”
A especificação do Product Feed opera com linhas/registros, cada uma descrevendo uma configuração vendável. O padrão arquitetural recomendado pela indústria (e bem alinhado ao feed da OpenAI) é: cada configuração separada (tamanho, duração da assinatura, plano, região) é um registro separado no feed, ou seja, um SKU separado.
O produto base vive no seu modelo interno; no feed você trabalha no nível de SKU.
Por exemplo, se você tem um serviço com assinaturas de 1, 3 e 6 meses, do ponto de vista do product feed são SKUs diferentes. Se um serviço pode ser comprado em 20 condições distintas, no product feed você terá 20 SKUs.
Em TypeScript, isso poderia ser expresso assim:
// Modelo interno do GiftGenius
export interface GiftProduct {
id: string; // product_123
name: string;
description: string;
baseImageUrl: string;
}
// SKU que irá para o Product Feed
export interface GiftSkuFeedItem {
id: string; // product_123_usd_1m
productId: string; // referência a GiftProduct.id
title: string;
description: string;
price: number; // em unidades mínimas (centavos)
currency: string; // "usd"
}
Dentro do GiftGenius você pode ter uma relação um‑para‑muitos entre GiftProduct e GiftSkuFeedItem. E no feed você expõe uma lista “plana” de SKUs.
Para que o ChatGPT entenda quais SKUs pertencem a um mesmo produto base (por exemplo, assinatura de 1, 3 e 12 meses), costuma‑se usar um campo de agrupamento como item_group_id. No entanto, isso é um padrão arquitetural, não uma exigência rígida do padrão.
Por exemplo:
{
"id": "gg-coffee-sub-1m-usd", // SKU da assinatura de 1 mês
"item_group_id": "gg-coffee-sub", // Seu produto
"title": "Assinatura de café — 1 mês",
"price": 2900,
"currency": "usd",
"enable_search": true,
"enable_checkout": true
}E para a assinatura de 3 meses:
{
"id": "gg-coffee-sub-3m-usd", // SKU da assinatura de 3 meses
"item_group_id": "gg-coffee-sub", // O mesmo id do produto
"title": "Assinatura de café — 3 meses",
"price": 7900,
"currency": "usd",
"enable_search": true,
"enable_checkout": true
}Essa abordagem facilita a vida do modelo e do seu backend ao criar pedidos: o ID do SKU se torna a chave exclusiva pela qual você sempre encontra a configuração exata que o usuário comprou.
4. Campos obrigatórios do Product Feed e seu impacto no UX
Na especificação do Product Feed, a OpenAI divide os campos em três grupos: obrigatórios (required), recomendados (recommended) e opcionais (optional).
Os nomes e listas específicos devem ser consultados na documentação atualizada, mas, para fins didáticos, podemos nos apoiar neste conjunto “mínimo”.
| Campo | Para que serve | O que acontece se estiver ausente |
|---|---|---|
|
Identificador exclusivo do SKU no escopo do merchant | O item não pode ser identificado de forma unívoca |
|
Título curto para o card | Fica mais difícil para o modelo entender do que se trata o item |
|
Descrição detalhada | As respostas serão mais genéricas; pior personalização |
|
Preço em unidades mínimas | Impossível preparar o checkout |
|
Código de moeda ISO 4217, geralmente em minúsculas | A plataforma não saberá em que moeda calcular |
|
URL da página do produto no site do merchant | O usuário não poderá ir ao seu site |
|
Status de disponibilidade (in_stock, out_of_stock etc.) | Itens indisponíveis podem ser exibidos |
|
Permite usar o item na pesquisa | Sem true, o item não aparecerá nos resultados |
|
Permite compra via Instant Checkout | Será apenas discovery/link‑out |
Um ponto importante: enable_search e enable_checkout separam logicamente os modos de operação.
Se enable_search = true e enable_checkout = false, o item pode aparecer na busca, mas, ao tentar comprar, o usuário irá pelo seu link (link) para o seu site, e não para o Instant Checkout dentro do ChatGPT (onde o cartão já está salvo).
Se enable_checkout = true, então, cumpridas as demais condições (região suportada, moeda, backend ACP válido), o item pode ser comprado diretamente no ChatGPT com um ou dois cliques (o que aumenta bastante a conversão).
Exemplo de objeto “minimamente adequado” do GiftGenius para checkout:
{
"id": "gg-dev-notebook-plain-usd",
"title": "Caderno minimalista para desenvolvedor",
"description": "Preto, sem linhas, 120 páginas. Para quem escreve especificações à mão.",
"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
}Observe: mesmo no exemplo adicionamos uma imagem (image_link) — formalmente ela pode ser recomendada, e não obrigatória, mas sem ela o UX fica bem pior.
5. Campos recomendados e opcionais: como deixar o feed “mais atraente”
Os campos obrigatórios servem “para que funcione”. Mas, se você parar por aí, terá algo como um CSV minimamente válido para a contabilidade, não uma vitrine de IA caprichada.
Os campos recomendados normalmente incluem:
- URL principal e adicionais de imagens;
- categoria do produto (frequentemente baseada em uma taxonomia, como “presentes > experiências > cursos online”);
- marca/nome do merchant;
- atributos como cor, tamanho, material;
- flags de conteúdo adulto, restrições etárias etc.
Quanto mais rico for o seu item, respostas mais significativas o modelo conseguirá gerar. Por exemplo, se você especifica que o caderno é feito de papel reciclado e “apoia desenvolvedores preocupados com o planeta”, o ChatGPT pode recomendá‑lo conscientemente a um usuário que pediu presentes ecológicos.
No GiftGenius, poderíamos expandir a descrição desse SKU:
{
"id": "gg-dev-notebook-plain-usd",
"title": "Caderno ecológico para desenvolvedor",
"description": "Caderno minimalista sem pauta, 120 páginas de papel reciclado.",
"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
}Atributos adicionais como category e brand não apenas melhoram os resultados, mas também ajudam na análise: você pode ver quais categorias convertem melhor via ChatGPT e quais convertem pior.
Os campos opcionais costumam estar ligados a cenários muito específicos (por exemplo, parâmetros geográficos de preços, dos quais falaremos à parte, ou metadados personalizados). Eles devem ser adicionados conforme o projeto amadurece, e não apenas “para constar”.
6. Flags comerciais e modo somente discovery
Vamos fixar novamente a lógica de enable_search e enable_checkout, pois isso é a ponte crítica para as próximas aulas sobre ACP e Instant Checkout.
Imagine que você está começando como merchant no ChatGPT. Você tem um catálogo de presentes, mas o backend ACP e o Delegated Payment ainda estão em desenvolvimento. Você já quer que o ChatGPT encontre seus SKUs e envie os usuários ao seu site para pagar.
Nesse caso, você:
- publica o Product Feed com enable_search = true para os SKUs desejados;
- deixa enable_checkout = false até empacotar e certificar a integração ACP.
O ChatGPT poderá incluir seus presentes nas respostas aos usuários, mostrar cartões e oferecer um link “Ir para o site da GiftGenius”, mas não construirá a interface interna do Instant Checkout.
Quando você implementar o Agentic Checkout e o Delegated Payment, determinados produtos podem ser colocados no modo “prontos para Instant Checkout” — basta definir enable_checkout = true e, adicionalmente, cumprir todos os requisitos de dados (preço, moeda, seller URL etc.).
No nível das especificações, os campos do Product Feed serão usados para preencher os line_items e o total na checkout_session.
Assim, o feed se torna uma alavanca de ajuste fino: quais SKUs e em que condições o ChatGPT está autorizado a vender em seu nome.
7. Locales, moedas, regiões e preços multirregionais
Você provavelmente sabe que o mundo não se limita a en-US e dólares. Nos módulos sobre localização, já discutimos como locale e userLocation afetam a lógica de negócio. Aqui isso ganha protagonismo: produtos na Alemanha podem ter preços diferentes dos dos EUA, e alguns presentes podem simplesmente não poder ser vendidos em certos países.
A especificação do Product Feed leva isso em conta por meio de vários mecanismos.
Primeiro, a moeda: currency deve ser um código ISO 4217 válido (por exemplo, usd, eur, gbp).
Segundo, podem ser usados campos que descrevem preço e disponibilidade geodependentes. A documentação traz exemplo de atributos como geo_price e códigos regionais associados, baseados na ISO 3166.
Existem duas abordagens arquiteturais básicas.
Abordagem 1: um feed por região.
- product-feed-us-en.json para os EUA;
- product-feed-de-de.json para a Alemanha;
- product-feed-br-pt.json para o Brasil.
Em cada feed, todos os SKUs já estão na moeda e locale desejados. É mais simples para o ChatGPT, mas dá mais trabalho para você manter vários feeds.
Abordagem 2: um feed único com campos geográficos.
Dentro de cada registro, você armazena um array de preços ou atributos adicionais:
{
"id": "gg-dev-notebook-multi",
"title": "Caderno ecológico para desenvolvedor",
"description": "Apoia seu amor por código limpo e pelo planeta.",
"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
}A estrutura exata dos campos multirregionais depende da versão da especificação, mas a ideia é uma só: o feed deve permitir à plataforma entender em quais países o SKU existe e quanto ele custa em cada um.
Do ponto de vista do GiftGenius, é importante planejar o mapeamento entre:
- locale e userLocation, que o ChatGPT conhece;
- e a parte do feed da qual devem ser obtidos os preços e textos.
Na maioria dos cenários comerciais, você não expõe um único registro “para o mundo todo”, mas cria SKUs diferentes por país, para simplificar o cumprimento de impostos, políticas e restrições de produtos.
8. Qualidade dos dados e política: sem isso o Instant Checkout não decola
Product Feed não é apenas sobre formato, mas também sobre qualidade dos dados e conformidade com as políticas da OpenAI.
No quesito qualidade, a OpenAI exige explicitamente:
- identificadores corretos e estáveis;
- URLs válidos com HTTPS e código de resposta 200;
- consistência entre preço e moeda;
- disponibilidade atualizada (não deve haver in_stock para itens que na verdade acabaram).
A especificação também define exigências de tamanho de texto: por exemplo, title não deve ser longo demais (centenas de caracteres), e description tem um limite razoável (milhares de caracteres), para que os cards fiquem organizados e não virem um romance em três volumes.
Um bloco à parte é a Prohibited Products Policy. É a lista de categorias de produtos e serviços que não podem ser vendidos via Instant Checkout e/ou pelo ChatGPT em geral: itens óbvios como produtos ilegais, armas, alguns serviços médicos etc. Os detalhes devem ser verificados sempre na política atual, mas o importante para nós é perceber: o Product Feed será verificado não apenas quanto ao formato, mas também quanto à permissibilidade do conteúdo.
Se seu catálogo contém categorias ambíguas (por exemplo, álcool, jogos de azar ou algo relacionado a crianças), trate essas seções com atenção redobrada. Muitas vezes é mais simples mantê‑las com enable_checkout = false e vender apenas pelo seu próprio site, com toda a cobertura jurídica.
9. Prática: montando um Product Feed mínimo para a GiftGenius
Agora vamos aplicar tudo isso na prática e montar um feed simples para três SKUs da GiftGenius. Suponha que temos:
- Caderno ecológico para desenvolvedor.
- Assinatura de café por 1 mês.
- Vale‑presente para o curso “TypeScript para adultos”.
Primeiro, definimos o tipo TypeScript que usaremos para gerar o feed:
export interface GiftGeniusFeedItem {
id: string;
title: string;
description: string;
price: number; // em centavos
currency: "usd" | "eur";
availability: "in_stock" | "out_of_stock";
link: string;
image_link?: string;
enable_search: boolean;
enable_checkout: boolean;
}Agora criamos no código um array com alguns elementos e depois o serializamos em JSON:
export const giftGeniusFeed: GiftGeniusFeedItem[] = [
{
id: "gg-eco-notebook-usd",
title: "Caderno ecológico para desenvolvedor",
description: "Caderno minimalista sem pauta feito de papel reciclado.",
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: "Assinatura de café para desenvolvedor — 1 mês",
description: "Caixa mensal de café em grãos. Compatível com prazos.",
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: "Vale-presente para o curso de TypeScript",
description: "Curso online para desenvolvedores que finalmente querem entender 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 // por enquanto, apenas discovery
}
];Depois, você pode criar uma utilidade simples que gere a cada N minutos o arquivo product-feed.json a partir dessa estrutura e o publique no seu servidor HTTPS.
import { writeFile } from "node:fs/promises";
import { giftGeniusFeed } from "./feed-data";
// Gerador mais simples de feed JSON
async function buildProductFeed() {
const json = JSON.stringify(giftGeniusFeed, null, 2);
await writeFile("public/product-feed.json", json, "utf8");
}
buildProductFeed().catch(console.error);Claro que, em um projeto real, você não manterá todo o feed no código; em vez disso, os dados virão do banco. Mas, para começar, vale montar ao menos esse exemplo didático para testar o pipeline: geração → publicação → validação.
10. Antiexemplo: como é um Product Feed “ruim”
Para entender melhor os requisitos da especificação e do UX, é útil ver um exemplo de feed que formalmente quase funciona, mas na prática causará problemas:
{
"id": "1",
"title": "Presente",
"description": "Presente legal",
"price": 12.333333,
"currency": "usdollars",
"availability": "yes",
"link": "http://giftgenius.local/gift/1",
"enable_search": "true",
"enable_checkout": "maybe"
}Aqui dá para contar vários problemas de imediato.
Em primeiro lugar, id = "1" — é um identificador instável e pouco expressivo. Se algum dia você migrar o banco ou introduzir sharding, tais identificadores se tornam frágeis. É melhor usar IDs significativos e suficientemente longos, exclusivos no escopo do merchant.
Em segundo lugar, price foi indicado como número decimal com cauda infinita. As especificações e os sistemas de pagamento normalmente esperam o preço em unidades mínimas (centavos) como número inteiro, para evitar problemas de ponto flutuante e arredondamento.
Em terceiro lugar, currency = "usdollars" e availability = "yes" não correspondem aos formatos esperados (ISO 4217 e a lista de status permitidos).
Em quarto lugar, o link aponta para http e um domínio local — ambos inaceitáveis para produção real; a especificação exige HTTPS e disponibilidade pública.
Em quinto lugar, os flags enable_search e enable_checkout devem ser booleanos, não strings. Caso contrário, o parser da OpenAI pode rejeitar o feed ou aplicar um padrão que pode te surpreender negativamente.
Esses problemas podem levar tanto a um erro rígido de validação (feed rejeitado) quanto a uma situação mais desagradável: o feed é aceito formalmente, mas parte dos SKUs é ignorada ou funciona de modo diferente do esperado. Por isso vale investir em validação interna ainda do seu lado.
11. Erros comuns ao trabalhar com Product Feed
Erro nº 1: pensar no feed como um “CSV pontual” para importação.
Às vezes, as equipes encaram o Product Feed como um arquivo que geram uma vez “para integração” e esquecem. No AI‑commerce não é assim: o feed é uma fonte viva da verdade que deve ser atualizada regularmente. Se você muda preços, retira itens de venda, lança promoções — tudo isso deve chegar ao feed em tempo hábil. Do contrário, o ChatGPT recomendará o que já não existe ou com preço antigo, e os usuários vão, com razão, se irritar.
Erro nº 2: misturar o modelo de produto com SKU.
Um antipadrão comum é tentar refletir um produto base com um monte de opções em um único registro do feed com muitos campos “size1/size2/size3” ou “duration1/duration2”. O resultado é que o modelo não entende o que exatamente está sendo vendido, e seu backend ACP sofre ao desempacotar esses campos no momento do checkout. Muito mais simples e confiável: um SKU — um registro no feed, mesmo que seja apenas uma variante dentro do mesmo produto.
Erro nº 3: ignorar locales e regiões.
Desenvolvedores que fazem o primeiro MVP frequentemente colocam currency = "usd" e enable_checkout = true para tudo, sem considerar que o Instant Checkout pode não estar disponível no seu país ou que certos produtos não podem ser vendidos em alguns países por política ou lei. Depois, ao expandir para um novo mercado, tudo começa a quebrar: preços não batem, impostos não são considerados. É melhor, desde o início, vincular SKUs a regiões e moedas, mesmo que você tenha só um mercado por enquanto.
Erro nº 4: tratar descrições como textos de SEO do passado.
Algumas equipes copiam para o Product Feed descrições antigas de seus sites, às vezes escritas para “palavras‑chave” e robôs. Para o ChatGPT, isso é mais prejudicial do que útil: o modelo já sabe escrever textos; o que ele mais precisa são fatos estruturados, honestos e precisos. É melhor descrever de forma breve e objetiva do que encher a description de água de marketing por meia tela.
Erro nº 5: não validar o feed por conta própria.
Confiar apenas na validação do lado da OpenAI é receita para noites difíceis antes do prazo. Vale criar um validador simples no seu backend ou no CI que verifique os esquemas dos campos, valores permitidos, formatos de URL e moedas. Dá para fazer até em TypeScript usando, por exemplo, Zod ou verificações próprias. Assim, você pega os problemas antes mesmo de subir o feed para produção.
Erro nº 6: incluir “qualquer coisa” no Product Feed.
Às vezes dá vontade de enfiar milhares de SKUs no feed “para deixar lá, vai que precisam”. Na prática, isso dificulta depuração, análise e controle de qualidade. Muito mais sensato começar com um subconjunto limitado: apenas as categorias e SKUs que você está disposto a acompanhar e realmente quer vender pelo ChatGPT. O resto pode ficar em modo discovery ou mesmo sem integração.
Erro nº 7: não sincronizar o Product Feed e o backend ACP.
O feed e a API do ACP são duas faces da mesma moeda. Se surgiu um novo SKU no feed e seu backend ainda não consegue vendê‑lo (ou o contrário: o SKU foi removido do feed, mas o backend ainda acredita que ele existe), você terá dessincronização, bugs complexos e chamados difíceis no suporte. Boa prática é ter um único modelo de domínio do catálogo e usá‑lo tanto para gerar o feed quanto para processar o checkout.
GO TO FULL VERSION