Note de référence
Catalogue UCP : Search, Lookup et identifiants produit
Comment exposer un catalogue UCP avec Search et Lookup, stabiliser les identifiants et relier découverte produit et checkout.
Publiée le . Rattachée à la lisibilité du catalogue par les agents.
La capacité Catalog d’UCP sépare deux besoins : Search découvre des produits à partir d’une requête et de filtres ; Lookup résout des identifiants déjà connus. Cette séparation évite de transformer chaque accès catalogue en recherche approximative.
En bref
- Catalog possède 2 capacités négociables : Search et Lookup.
- Un produit regroupe une ou plusieurs variantes achetables.
- Le prix du catalogue informe ; le checkout reste la source transactionnelle.
Cette note suit la release 2026-08-25. Cette version conserve la séparation entre
Search et Lookup, et enrichit Catalog avec les unités de vente fractionnaires, les
politiques applicables aux produits et les actions définies par des extensions.
Que couvre la capacité Catalog ?
La spécification Catalog décrit la recherche libre, la navigation par catégorie, le filtrage, la récupération par lot et la comparaison de prix entre variantes. Elle utilise des objets communs pour le contexte, les signaux et l’attribution.
Un Product porte le titre, la description, les médias et ses variantes. Une Variant
désigne une combinaison achetable, avec options, prix et disponibilité. Le montant est
exprimé dans l’unité mineure de la devise, accompagné d’un code ISO 4217.
Depuis la release 2026-08-25, variants[].quantity_unit peut aussi décrire l’unité,
l’échelle et l’incrément de vente. Son absence signifie que la variante est vendue à
l’unité. Cette distinction est nécessaire pour les produits vendus au poids, au volume,
à la longueur ou au temps.
Quand utiliser Search ?
Search répond à une intention comme « chaussures imperméables sous 120 euros ». La plateforme envoie une requête, un contexte de marché et des filtres. Le marchand garde la responsabilité du classement et de l’interprétation de ces critères.
Une recherche vide n’est pas nécessairement une erreur de transport. La réponse peut être valide avec une liste vide et des messages explicatifs. L’agent doit distinguer une absence de résultat d’un catalogue indisponible.
La qualité dépend directement des données exposées : titres discriminants, variantes normalisées, prix explicites, disponibilité courante et médias utilisables. La page GEO et catalogue lisible décrit ce socle sémantique.
Quand utiliser Lookup ?
Lookup fournit deux opérations. lookup_catalog reçoit un tableau ids[] et renvoie
les produits correspondants. get_product reçoit un seul identifiant pour fournir le
détail utile à une décision, notamment les options de variante.
Les implémentations doivent accepter l’identifiant produit et l’identifiant variante. Elles peuvent aussi accepter un SKU, un handle ou une URL si ce champ est renvoyé dans l’objet produit. Les doublons d’entrée doivent être dédupliqués, et un même produit ne doit apparaître qu’une fois.
| Besoin | Opération |
|---|---|
| résoudre plusieurs IDs | lookup_catalog |
| afficher une liste compacte | lookup_catalog |
| charger le détail d’un produit | get_product |
| sélectionner une variante | get_product |
Comment relier le catalogue au checkout ?
L’identifiant de variante renvoyé par Catalog doit correspondre à celui attendu dans
checkout.line_items[].item.id. Ce contrat évite une table de traduction implicite
entre découverte et transaction.
Les prix et disponibilités Catalog reflètent les conditions courantes pour la requête, mais ne constituent pas un engagement. Ils peuvent dépendre de la session et ne doivent pas être réutilisés sans validation. Le checkout reste la source faisant autorité au moment d’acheter.
Erreurs de conception à éviter
- Utiliser Search pour résoudre un SKU exact.
- Exposer un identifiant différent entre Catalog et Checkout.
- Mélanger produit et variante dans un même champ non typé.
- Mettre en cache un prix de recherche comme s’il était garanti.
- Ignorer la devise ou l’unité mineure du montant.
- Retourner un résultat partiel sans message lorsque certains IDs sont inconnus.
Checklist de qualité catalogue
- Search et Lookup sont annoncés séparément dans le manifeste ;
- les variantes ont des identifiants stables et achetables ;
- les filtres s’appliquent après la résolution des identifiants ;
- les réponses indiquent prix, devise et disponibilité ;
- les ventes hors unité déclarent
quantity_unitet leur incrément ; - les identifiants inconnus sont signalés sans invalider les correspondances valides ;
- le checkout revalide toujours le prix final.
La mise en production de ces contrats s’inscrit dans le guide d’implémentation UCP.
Sources
Revenir à la lisibilité du catalogue par les agents · Toutes les notes · Read in English