Panier UCP ou checkout : quelle capacité utiliser ?

Différences entre Cart et Checkout dans UCP, conversion du panier, états, paiements et règles d'implémentation côté marchand.

Publiée le 19 août 2026 . Rattachée à le guide d'implémentation UCP.

Dans UCP, Cart sert à construire un panier avant l’intention d’achat. Checkout sert à finaliser une transaction. Les deux capacités partagent des objets, mais elles n’ont ni le même niveau d’engagement, ni les mêmes contraintes de paiement.

En bref

Cart expose 4 opérations simples et ne requiert aucun gestionnaire de paiement.

Checkout expose 5 opérations et porte un cycle d’état jusqu’à la commande.

La conversion par cart_id doit rester idempotente.

Cart et Checkout répondent à deux moments différents

La spécification Cart réserve le panier à l’exploration : ajouter, retirer ou conserver des articles, obtenir des estimations localisées et partager une session avec continue_url. Le client n’a pas encore confirmé son intention d’acheter. Les totaux peuvent donc rester partiels.

Checkout commence lorsque cette intention existe. Il configure les moyens de paiement, collecte les informations nécessaires, traite les erreurs et fait évoluer la session vers une commande. La séquence type est explicite : panier, checkout, puis commande.

Critère	Cart	Checkout
Objectif	exploration avant achat	finalisation de l’achat
Paiement	absent	gestionnaires et instruments requis
Prix	estimation possible	prix faisant autorité
États	ressource présente ou absente	cycle d’état complet
Opérations	create, get, update, cancel	create, get, update, complete, cancel

Comment convertir un panier en checkout ?

Si le profil marchand annonce dev.ucp.shopping.cart, la création du checkout peut recevoir un cart_id. Le marchand doit alors initialiser la session avec le contenu du panier. En cas de doublon entre le panier et le corps de la requête, le contenu du panier fait autorité.

{
  "cart_id": "cart_abc123",
  "line_items": []
}

Cette conversion a une règle importante : si un checkout incomplet existe déjà pour ce cart_id, le marchand doit le renvoyer. Il ne doit pas créer une seconde session. Cette obligation évite deux paiements concurrents pour un même panier.

Pendant le checkout, la spécification recommande de maintenir le lien entre les deux ressources. Une modification de quantité peut ainsi être répercutée vers le panier. Après la commande, le marchand peut vider le panier selon sa durée de vie ou ses règles internes.

Quelles données sont communes ?

Cart réutilise les entités de Checkout : lignes, articles, acheteur, contexte, signaux, attribution, totaux, messages et liens. Ce choix réduit les transformations à la conversion. L’identifiant de variante découvert dans le catalogue doit rester celui attendu par line_items[].item.id.

La signification des totaux change toutefois. Dans un panier, taxes et livraison peuvent manquer si l’adresse n’est pas connue. Dans le checkout, le marchand doit produire les montants nécessaires à la décision et à la finalisation.

Quand faut-il implémenter Cart ?

Cart est utile si l’agent doit comparer plusieurs produits, reprendre une sélection, partager un panier ou passer temporairement par l’interface du marchand. Il est aussi adapté aux parcours où le contexte de marché permet une estimation avant de demander une adresse complète.

Checkout peut suffire pour un parcours court, lorsque l’article est déjà identifié et que l’intention d’achat est établie. UCP n’impose pas de déployer Cart avant Checkout. Chaque capacité est annoncée et négociée séparément dans le manifeste UCP.

Checklist d’implémentation

Annoncer Cart seulement si les 4 opérations sont réellement supportées.
Renvoyer des estimations clairement distinguées des prix de checkout.
Fournir un continue_url exploitable pour la reprise humaine.
Conserver un seul checkout incomplet par cart_id.
Répercuter les modifications utiles pendant la transition.
Traiter un panier expiré avec not_found, sans réutiliser silencieusement son ID.

Pour replacer cette transition dans l’architecture complète, voir le guide d’implémentation UCP.

Sources

Revenir à le guide d'implémentation UCP · Toutes les notes · Read in English