ChatGPT Ads
Publicité ChatGPT

Mise à jour incrémentale d'un flux produit (Delta Feeds API)

Idée centrale

La Delta Feeds API met à jour la disponibilité et le titre de variantes déjà existantes dans un flux produit lié, sans retéléverser l'intégralité du catalogue. C'est un mécanisme d'optimisation opérationnelle qui présuppose systématiquement un flux et un catalogue initial déjà en place, documentés dans Création de campagnes à flux produits via l'API Ads : elle ne crée pas de flux, ne téléverse pas de catalogue complet, et n'ajoute pas de produits absents du flux.

Définition

Le point de terminaison PATCH /feeds/{feed_id}/products de l'API Ads, qui accepte des mises à jour partielles (« deltas ») de disponibilité et de titre sur des produits et variantes déjà présents dans un flux lié à un compte publicitaire.

Contexte

Route activée par compte publicitaire, non universellement disponible : une réponse 403 portant le code product_feed_api_disabled ou product_feed_delta_api_disabled signifie que la fonctionnalité n'est pas activée pour ce compte, à résoudre en contactant l'équipe de compte OpenAI. Prérequis : une clé API Ads (voir Authentification, compte publicitaire et fichiers dans l'API Ads), un flux produit déjà lié au compte avec son identifiant, un catalogue initial déjà téléversé, et les identifiants existants du produit parent et de ses variantes. Capturée le 2026-08-08.

Fonctionnement

Mettre à jour des variantes de produits — PATCH /feeds/{feed_id}/products

curl -X PATCH \
  "https://api.ads.openai.com/v1/feeds/product_feed_123/products" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "id": "running-shoe-001",
        "variants": [
          {
            "id": "running-shoe-001-black-9",
            "availability": { "available": false }
          },
          {
            "id": "running-shoe-001-white-9",
            "title": "Running shoe - white, size 9",
            "availability": { "status": "in_stock" }
          }
        ]
      }
    ]
  }'

Réponse en cas de succès, 200 OK :

{ "id": "product_feed_123", "accepted": true }

Sémantique de accepted: true : « accepted: true means the update was accepted by feed processing. It doesn't mean downstream indexing, ad eligibility, or serving has already updated. » — il faut vérifier accepted avant de considérer la requête réussie, mais cela ne garantit pas la propagation en aval.

Champs de la requête

ChampTypeObligatoireDescription
productsobject[]OuiUn ou plusieurs produits existants à mettre à jour.
products[].idstringOuiIdentifiant du produit parent, issu du catalogue existant.
products[].variantsobject[]OuiUne ou plusieurs variantes existantes du produit parent.
products[].variants[].idstringOuiIdentifiant existant de la variante, issu du catalogue.
products[].variants[].titlestringNonTitre mis à jour pour cette variante.
products[].variants[].availabilityobjectNonDisponibilité mise à jour.
availability.availablebooleanNontrue = in_stock ; false = out_of_stock.
availability.statusstringNonDisponibilité explicite (in_stock, out_of_stock). Prévaut sur available si les deux sont présents.

Contraintes : products et chaque variants doivent contenir au moins un élément ; les identifiants doivent être non vides ; une même variante ne doit pas apparaître deux fois dans une même requête. Les champs shop_id, scoped_offer_id et target_country ne doivent pas être envoyés : la propriété du flux, l'identité du produit et les pays pris en charge sont résolus à partir du flux lié.

Application des changements

Le téléversement initial fournit l'enregistrement produit complet ; une requête delta ne modifie que les champs spécifiés sur des variantes existantes et préserve le reste des données. Une fois la mise à jour acceptée, les systèmes en aval appliquent le changement de façon asynchrone. Un produit passé hors stock cesse d'être éligible à la diffusion une fois le changement propagé ; marquer un produit en stock ne garantit pas sa diffusion — le produit, la campagne, le groupe d'annonces et l'annonce doivent toujours satisfaire les conditions normales d'éligibilité (voir Création de campagnes à flux produits via l'API Ads). La réponse d'acceptation ne contient ni horodatage de complétion ni résultat du traitement en aval.

Erreurs courantes

StatutCauseAction
400Champ obligatoire manquant, liste de produits/variantes vide, ou champ inconnu dans la requête.Vérifier le corps de la requête.
401Clé API Ads manquante ou invalide.Utiliser une clé API Ads active dans l'en-tête Authorization: Bearer.
403Accès à l'API de flux désactivé, ou permission insuffisante.Vérifier les permissions du compte, contacter l'équipe de compte OpenAI.
404Flux inexistant ou non lié au compte associé à la clé API.Vérifier l'identifiant du flux et la clé API du compte propriétaire.

Éléments essentiels

Distinctions importantes

Ne pas confondre accepted: true (la requête a passé le traitement du flux) avec une confirmation que le changement est déjà indexé, éligible aux annonces, ou en diffusion : ce sont trois étapes distinctes, asynchrones.

Ne pas confondre cette route (PATCH, mises à jour incrémentales de variantes existantes) avec la connexion initiale du flux ou le téléversement complet du catalogue, qui restent hors de l'API publique et se font par SFTP depuis Ads Manager — voir Création de campagnes à flux produits via l'API Ads.

Cas pratiques

Aucun cas pratique disponible : identifiants et exemples (running-shoe-001, product_feed_123) manifestement fictifs et illustratifs.

Erreurs fréquentes

Ne pas envoyer shop_id, scoped_offer_id ou target_country dans le corps de la requête : ces champs sont résolus automatiquement à partir du flux lié et provoquent une erreur 400 s'ils sont inclus (champ inconnu).

Ne pas considérer un produit remis en stock (availability.status: "in_stock") comme immédiatement servi : la campagne, le groupe d'annonces et l'annonce doivent aussi satisfaire les conditions normales d'éligibilité.

Ne pas répéter une même variante deux fois dans la même requête.

Limites et nuances

Relations

Points à vérifier

Sources