Commande de courses

Ce guide décrit un exemple d'intégration pour une expérience de commande de courses à l'aide de l'UCP (Universal Commerce Protocol). Le protocole MCP (Model Context Protocol) et le REST sont tous deux des liaisons de transport prises en charge, mais le MCP est recommandé afin de mieux s'aligner sur la mission des Applis connectées.

Important : Le tableau buyer_address_locations et le champ context.buyer_address_location mentionnés dans ce guide sont des extensions de fournisseur spécifiques à Google et ne font pas partie de la spécification UCP principale. Ces extensions sont fournies pour permettre la commande de courses à livrer en fonction des préférences connues de l'utilisateur.

Remarque : Ce parcours utilisateur suppose que le compte Google de l'utilisateur soit déjà associé à son compte sur votre plate-forme. Pour en savoir plus sur l'implémentation de l'association de comptes, consultez le guide sur OAuth 2.1. Pour obtenir la liste des autorisations à configurer, consultez Niveaux d'accès UCP requis.

Dans ce scénario, un utilisateur a trouvé une recette en ligne (non détaillée dans ce guide) et souhaite acheter les ingrédients nécessaires :

• 4 cuillères à soupe de beurre salé
• 3 gousses d'ail
• 1 oignon jaune
• 1 boîte de 800 g de tomates pelées entières
• 225 g de pâtes

Transports

Cette section décrit les principales différences entre les deux liaisons de transport.

Protocole MCP (Model Context Protocol)

Le transport MCP permet aux agents IA d'interagir avec vos fonctionnalités à l'aide d'appels d'outils structurés via JSON-RPC 2.0 :

• Protocole de communication : fonctionne sur JSON-RPC 2.0 (stdio, SSE ou Stream).
• Enveloppe de requête : les requêtes appellent tools/call, où params.name identifie l'outil (par exemple, search_locations, search_catalog, create_cart, update_cart, get_cart, lookup_locations, cancel_cart). Les métadonnées (telles que ucp-agent et idempotency-key) sont transmises dans params.arguments.meta, tandis que les paramètres de fonctionnalité sont encapsulés dans un objet conteneur spécifique à la fonctionnalité (location, catalog ou cart).
• Enveloppe de réponse : les réponses renvoient un résultat JSON-RPC 2.0 avec des charges utiles encapsulées dans result.structuredContent, contenant des métadonnées de fonctionnalité ucp de premier niveau ainsi que des champs de réponse de fonctionnalité.

REST

Le transport REST utilise les modèles de ressources HTTP/1.1+ et RESTful standards :

• Protocole de communication et sécurité : les requêtes et les réponses utilisent Content-Type: application/json via HTTPS (TLS 1.3 minimum).
• Méthodes et chemins d'accès : les verbes HTTP standards sont directement mappés aux fonctionnalités :
  • POST /locations/search : rechercher des lieux et des adresses enregistrées
  • POST /locations/lookup : rechercher des lieux par identifiant
  • POST /catalog/search : rechercher des produits et leur disponibilité
  • POST /carts : créer une session de panier
  • PUT /carts/{id} : mettre à jour une session de panier
  • GET /carts/{id} : récupérer une session de panier
  • POST /carts/{id}/cancel : annuler une session de panier
• En-têtes : les métadonnées sont transmises via des en-têtes HTTP standards :
  • Host : nom d'hôte du serveur cible, par exemple business.example.com
  • UCP-Agent : URI du profil de plate-forme dans la syntaxe de champ structuré du dictionnaire RFC 8941, par exemple profile="https://platform.example/profiles/grocery-agent.json"
  • Idempotency-Key : chaîne UUID pour les opérations de modification d'état (comme l'annulation du panier) pour des nouvelles tentatives sécurisées
  • Request-Id : identifiant de requête facultatif pour le traçage de bout en bout
• Charges utiles et réponses : les corps de requête et de réponse contiennent directement le schéma JSON de la fonctionnalité brute, sans enveloppes JSON-RPC ni conteneurs de wrapper d'outil. Les réponses réussies renvoient des codes d'état HTTP standards (200 OK, 201 Created).

---

Présentation du flux

Le tableau suivant décrit la séquence d'appels entre l'agent Google et votre serveur :

Étape	Opération	Action de l'utilisateur et description	Réponse
1	search_locations	Rechercher des adresses de magasins et des adresses de livraison enregistrées par l'utilisateur	Renvoie les adresses des magasins, les adresses de livraison enregistrées et les messages d'information pour indiquer à l'agent de désambiguïser la localisation
2	search_catalog	Rechercher des produits d'après la localisation	Renvoie les produits, les prix et les variantes correspondants à l'aide des requêtes et des indices de localisation transmis dans la requête
3	create_cart	Créer un panier avec les variantes sélectionnées	Renvoie les détails du panier et un continue_url pour le paiement
4	update_cart	Mettre à jour le panier pour remplacer un produit choisi par une variante	Renvoie les détails du panier et un continue_url pour le paiement
5	get_cart	Récupérer un panier créé précédemment pour reprendre une session	Renvoie les détails du panier et un continue_url pour le paiement
6	lookup_locations	Rechercher les adresses de magasins et de livraison par identifiant chaque fois que l'UI du panier doit être présentée à l'utilisateur (pour afficher l'adresse sélectionnée dans l'interface)	Renvoie les adresses résolues de magasin et de livraison de l'acheteur
7	cancel_cart	Annuler une session de panier lorsque l'utilisateur recommence ou abandonne la commande	Renvoie l'état du panier avant la suppression

Remarque : Pour toutes les opérations sur le panier, seul l'élément title est utilisé pour afficher les éléments de l'interface utilisateur. Par conséquent, assurez-vous que le titre lui-même est explicite pour les utilisateurs.

Par défaut, la livraison est considérée comme le mode de traitement de la commande. Les utilisateurs peuvent passer au retrait en magasin via une invite explicite.

Les parcours utilisateur couvrent trois scénarios. Ces scénarios dépendent de l'intention de traitement (livraison ou retrait) ainsi que des adresses de livraison et des lieux de retrait en magasin de l'utilisateur qui sont enregistrés dans votre système :

• Scénario A : livraison, une ou plusieurs adresses
• Scénario B : livraison, aucune adresse
• Scénario C : retrait, pas d'adresse de magasin

Remarque : Le scénario "Retrait avec une adresse de magasin enregistrée" est semblable au scénario C, sauf que l'agent reçoit une liste d'adresses de magasins lors du premier appel search_locations, ignore le deuxième appel search_locations et passe immédiatement à la recherche dans le catalogue, en transmettant l'ID du magasin sélectionné par l'utilisateur dans context.location.

Recherche de lieux

Avant de rechercher dans le catalogue ou de créer un panier, l'agent effectue une recherche de lieux à l'aide de search_locations. Cette étape valide à la fois les adresses de magasins physiques et les adresses de livraison enregistrées par l'utilisateur dans son profil sur votre application, afin de les intégrer aux opérations UCP ultérieures (telles que la recherche dans le catalogue localisé et la gestion du panier).

• Opération/Outil : search_locations
• Fonctionnalité : dev.ucp.common.location.search
• Spécifications de transport : spécification MCP et spécification REST

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_locations",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "location": {}
    }
  }
}

REST

POST /locations/search HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab01
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{}

---

Scénario A : Livraison, une ou plusieurs adresses

Dans ce scénario, l'utilisateur souhaite se faire livrer des courses, et une ou plusieurs adresses de livraison sont associées à son compte dans votre système, qui contient par ailleurs un certain nombre d'adresses de magasins (non utilisées dans le parcours utilisateur de livraison).

1. L'agent appelle search_locations.
2. Votre serveur UCP renvoie l'adresse de magasin enregistrée par l'utilisateur dans la liste locations, ainsi que ses adresses de livraison figurant dans la liste buyer_address_locations.
3. Dans le cas de plusieurs adresses de livraison, le modèle traite la première adresse de la liste ("addr_user_home_01") comme l'adresse sélectionnée ou préférée. Vous devez renvoyer les adresses par ordre de préférence de l'utilisateur. Si aucun mécanisme de préférence n'existe, procédez par ordre d'utilisation, du plus récent au plus ancien.
4. Les requêtes d'opération de catalogue et de panier suivantes transmettent l'ID de l'adresse de livraison à titre d'indication dans context.buyer_address_location.
5. L'utilisateur peut modifier son adresse de livraison plus loin dans le parcours d'achat, ce qui entraîne la reconstruction du panier pour la nouvelle localisation, avec d'éventuelles mises à jour des articles selon les stocks locaux.

Réponse

Vous renvoyez l'adresse du magasin et les adresses de livraison enregistrées par l'utilisateur. Pour optimiser les performances, limitez la liste à 10 entrées maximum.

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [
        {
          "id": "loc_valley_grocers_chicago_clark",
          "name": "Valley Grocers - Lincoln Park",
          "address": {
            "street_address": "2200 N Clark St",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        }
      ],
      "buyer_address_locations": [
        {
          "id": "addr_user_home_01",
          "name": "Home",
          "address": {
            "street_address": "2200 N Clark St, Apt 4B",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        },
        {
          "id": "addr_user_work_02",
          "name": "Work",
          "address": {
            "street_address": "100 S State St, Floor 12",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60603"
          }
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [
    {
      "id": "loc_valley_grocers_chicago_clark",
      "name": "Valley Grocers - Lincoln Park",
      "address": {
        "street_address": "2200 N Clark St",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    }
  ],
  "buyer_address_locations": [
    {
      "id": "addr_user_home_01",
      "name": "Home",
      "address": {
        "street_address": "2200 N Clark St, Apt 4B",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    },
    {
      "id": "addr_user_work_02",
      "name": "Work",
      "address": {
        "street_address": "100 S State St, Floor 12",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60603"
      }
    }
  ]
}

Réponse (partenaires de livraison uniquement)

Les partenaires qui ne proposent que la livraison doivent renvoyer le message d'information pickup_not_supported dans search_locations. Respectez la formulation exacte du message ci-dessous :

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [],
      "messages": [
        {
          "type": "info",
          "code": "pickup_not_supported",
          "content": "In store pickup is not supported. Only delivery is available."
        }
      ],
      "buyer_address_locations": [
        {
          "id": "addr_user_home_01",
          "name": "Home",
          "address": {
            "street_address": "2200 N Clark St, Apt 4B",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        },
        {
          "id": "addr_user_work_02",
          "name": "Work",
          "address": {
            "street_address": "100 S State St, Floor 12",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60603"
          }
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [],
  "messages": [
    {
      "type": "info",
      "code": "pickup_not_supported",
      "content": "In store pickup is not supported. Only delivery is available."
    }
  ],
  "buyer_address_locations": [
    {
      "id": "addr_user_home_01",
      "name": "Home",
      "address": {
        "street_address": "2200 N Clark St, Apt 4B",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    },
    {
      "id": "addr_user_work_02",
      "name": "Work",
      "address": {
        "street_address": "100 S State St, Floor 12",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60603"
      }
    }
  ]
}

---

Scénario B : Livraison, aucune adresse

Dans ce scénario, l'utilisateur souhaite recevoir sa commande, mais aucune adresse de livraison n'est associée à son compte dans votre système (qui contient par ailleurs un certain nombre d'adresses de retrait en magasin). Le modèle invite l'utilisateur à saisir un code postal, qui est ensuite utilisé à titre d'indication dans les opérations ultérieures sur le catalogue et le panier. L'adresse de livraison finale est validée lors du règlement dans votre application ou sur votre site Web.

1. L'agent appelle search_locations.
2. Vous renvoyez les adresses de retrait en magasin enregistrées par l'utilisateur, une liste buyer_address_locations vide et un message d'information indiquant qu'aucune adresse de livraison n'est stockée dans le compte.
3. L'agent invite l'utilisateur à saisir son code postal.
4. L'utilisateur fournit son code postal (par exemple, 60614).
5. Lors des requêtes d'opération de catalogue et de panier suivantes, l'agent transmet le code postal à titre d'indication dans context.postal_code. L'adresse de livraison complète est saisie ultérieurement lors du processus de paiement sur votre site Web (continue_url).

Réponse

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [
        {
          "id": "loc_valley_grocers_chicago_clark",
          "name": "Valley Grocers - Lincoln Park",
          "address": {
            "street_address": "2200 N Clark St",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        }
      ],
      "buyer_address_locations": [],
      "messages": [
        {
          "type": "info",
          "code": "no_delivery_addresses_stored",
          "content": "No delivery addresses stored on the linked account."
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [
    {
      "id": "loc_valley_grocers_chicago_clark",
      "name": "Valley Grocers - Lincoln Park",
      "address": {
        "street_address": "2200 N Clark St",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    }
  ],
  "buyer_address_locations": [],
  "messages": [
    {
      "type": "info",
      "code": "no_delivery_addresses_stored",
      "content": "No delivery addresses stored on the linked account."
    }
  ]
}

Interaction de l'utilisateur :

• Requête de l'agent : l'agent demande "Quel est votre code postal de livraison ?".
• Réponse de l'utilisateur : l'utilisateur répond par 60614.
• Action de l'agent : l'agent transmet ensuite 60614 dans l'indication de localisation context.postal_code pour la recherche dans le catalogue et les opérations ultérieures sur le panier.
• Traitement : la validation de l'adresse de livraison s'effectue au moment du paiement sur votre application ou votre site Web.

Réponse (adresse de livraison enregistrée requise)

Si vous exigez que l'utilisateur ait enregistré une adresse de livraison sur son compte associé pour poursuivre un parcours de livraison (au lieu de revenir à une indication de code postal), vous pouvez renvoyer la réponse d'erreur récupérable suivante à search_locations.

Important : Les champs code et content du tableau messages doivent correspondre exactement (mot pour mot) aux valeurs affichées pour que l'agent reconnaisse et gère correctement cette erreur.

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "status": "error",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [],
      "messages": [
        {
          "type": "error",
          "code": "buyer_address_locations_required",
          "content": "The partner you are trying to connect with this tool doesn't have any saved delivery address for the linked account. Inform the user they must first add a delivery address for their linked account on partner's app/website, then continue the journey here.",
          "severity": "recoverable"
        }
      ],
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "status": "error",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [],
  "messages": [
    {
      "type": "error",
      "code": "buyer_address_locations_required",
      "content": "The partner you are trying to connect with this tool doesn't have any saved delivery address for the linked account. Inform the user they must first add a delivery address for their linked account on partner's app/website, then continue the journey here.",
      "severity": "recoverable"
    }
  ]
}

---

Scénario C : retrait, pas d'adresse

Dans ce scénario, l'utilisateur exprime son intention de retirer une commande, mais n'a enregistré aucune adresse de retrait en magasin dans votre système.

Remarque : Dans ce scénario, l'utilisateur n'a enregistré aucune adresse de livraison, ce qui n'a pas d'incidence sur l'expérience de retrait, mais permet de montrer comment gérer l'absence d'adresse de livraison et de retrait en magasin.

1. L'agent appelle search_locations.
2. Vous renvoyez une liste vide pour locations et buyer_address_locations, ainsi qu'un message d'information indiquant qu'aucune adresse de retrait en magasin n'a été enregistrée.
3. L'agent invite l'utilisateur à saisir son code postal.
4. L'utilisateur fournit son code postal (par exemple, 60614).
5. L'agent émet un deuxième appel search_locations en spécifiant serves.address.postal_code.
6. Vous renvoyez une liste d'adresses de magasins susceptibles de couvrir ce code postal.
7. S'il y a plusieurs adresses de magasins, le modèle traite la première de la liste comme l'adresse sélectionnée ou préférée. Vous devez renvoyer les adresses de magasins par ordre de préférence de l'utilisateur. Si aucun mécanisme de préférence n'existe, procédez par ordre d'utilisation, du plus récent au plus ancien.
8. Les requêtes d'opérations de catalogue et de panier suivantes incluent l'ID du magasin dans context.location à titre d'indication (conformément à la demande d'extraction 642).

Réponse 1

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [],
      "buyer_address_locations": [],
      "messages": [
        {
          "type": "info",
          "code": "no_pickup_locations_stored",
          "content": "No stored pickup store locations found for the linked account."
        },
        {
          "type": "info",
          "code": "no_delivery_addresses_stored",
          "content": "No delivery addresses stored on the linked account."
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [],
  "buyer_address_locations": [],
  "messages": [
    {
      "type": "info",
      "code": "no_pickup_locations_stored",
      "content": "No stored pickup store locations found for the linked account."
    },
    {
      "type": "info",
      "code": "no_delivery_addresses_stored",
      "content": "No delivery addresses stored on the linked account."
    }
  ]
}

Interaction de l'utilisateur :

• Invite de l'agent : l'agent demande : "Indiquez votre code postal pour trouver des points de retrait en magasin à proximité."
• Réponse de l'utilisateur : l'utilisateur répond par 60614.

Requête 2 (recherche de magasins à proximité par code postal)

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_locations",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "location": {
        "serves": {
          "address": {
            "postal_code": "60614"
          }
        }
      }
    }
  }
}

REST

POST /locations/search HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab02
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "serves": {
    "address": {
      "postal_code": "60614"
    }
  }
}

Réponse 2

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [
        {
          "id": "loc_valley_grocers_chicago_clark",
          "name": "Valley Grocers - Lincoln Park",
          "address": {
            "street_address": "2200 N Clark St",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        },
        {
          "id": "loc_valley_grocers_chicago_halsted",
          "name": "Valley Grocers - Lakeview",
          "address": {
            "street_address": "3200 N Halsted St",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60657"
          }
        }
      ],
      "buyer_address_locations": [],
      "messages": [
        {
          "type": "info",
          "code": "no_delivery_addresses_stored",
          "content": "No delivery addresses stored on the linked account."
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [
    {
      "id": "loc_valley_grocers_chicago_clark",
      "name": "Valley Grocers - Lincoln Park",
      "address": {
        "street_address": "2200 N Clark St",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    },
    {
      "id": "loc_valley_grocers_chicago_halsted",
      "name": "Valley Grocers - Lakeview",
      "address": {
        "street_address": "3200 N Halsted St",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60657"
      }
    }
  ],
  "buyer_address_locations": [],
  "messages": [
    {
      "type": "info",
      "code": "no_delivery_addresses_stored",
      "content": "No delivery addresses stored on the linked account."
    }
  ]
}

Sélection de l'utilisateur :

• Sélection de l'utilisateur : l'utilisateur sélectionne Valley Grocers - Lincoln Park (loc_valley_grocers_chicago_clark).
• Action de l'agent : l'agent procède ensuite à la recherche dans le catalogue, en transmettant "location": "loc_valley_grocers_chicago_clark" dans context.

Remarque : Le scénario "Retrait avec une adresse de magasin enregistrée" est semblable au scénario C, sauf que l'agent reçoit une liste d'adresses de magasins lors du premier appel search_locations, ignore le deuxième appel search_locations et passe immédiatement à la recherche dans le catalogue, en transmettant l'ID du magasin sélectionné par l'utilisateur dans context.location.

---

Recherche dans le catalogue

L'agent recherche les ingrédients dans le catalogue du marchand. L'agent effectue un appel search_catalog par ingrédient. Pour la disponibilité localisée et la tarification spécifique au magasin, l'agent inclut l'indication de localisation validée à l'étape 1 dans l'objet context de la requête.

Les exemples suivants montrent la requête et la réponse pour la recherche de "beurre salé". L'agent répète ce processus pour les autres ingrédients : ail, oignon jaune, tomates pelées entières et pâtes.

Remarque : Dans les opérations de catalogue et de panier, la méthode de traitement est entièrement déterminée par les indications de localisation dans la requête UCP. La présence de context.location indique un retrait dans le magasin spécifié. La présence de context.buyer_address_location indique une livraison à cette adresse. La présence de context.postal_code indique une livraison à une adresse dans ce code postal (auquel cas la validation de l'adresse est effectuée pendant le processus de paiement).

• Opération/Outil : search_catalog
• Fonctionnalité : dev.ucp.shopping.catalog.search (étendue avec des filtres dev.ucp.shopping.fulfillment)
• Spécifications de transport : spécification MCP et spécification REST

---

Scénario A : livraison avec indication de localisation par l'adresse de l'acheteur

Dans un parcours de livraison où l'utilisateur a enregistré une ou plusieurs adresses de livraison, l'agent transmet l'identifiant de localisation correspondant (par exemple, "buyer_address_location": "addr_user_home_01") dans l'objet context afin de récupérer les articles du catalogue et les prix disponibles pour cette adresse.

Requête (beurre ; adresse de livraison enregistrée)

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "catalog": {
        "query": "salted butter",
        "context": {
          "buyer_address_location": "addr_user_home_01"
        }
      }
    }
  }
}

REST

POST /catalog/search HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab03
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "query": "salted butter",
  "context": {
    "buyer_address_location": "addr_user_home_01"
  }
}

---

Scénario B : livraison avec indication de localisation par code postal

Dans un parcours de livraison où l'utilisateur n'a pas enregistré d'adresse de livraison (scénario B), l'agent transmet le code postal de livraison fourni par l'utilisateur (par exemple, "postal_code": "60614") dans l'objet context afin de récupérer les articles du catalogue et les prix disponibles pour cette zone.

Requête (beurre - livraison par code postal)

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "catalog": {
        "query": "salted butter",
        "context": {
          "postal_code": "60614"
        }
      }
    }
  }
}

REST

POST /catalog/search HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab04
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "query": "salted butter",
  "context": {
    "postal_code": "60614"
  }
}

---

Scénario C : retrait avec indication de localisation du magasin

Dans un parcours de retrait, l'agent transmet l'identifiant de localisation du magasin sélectionné (par exemple, "location": "loc_valley_grocers_chicago_clark") dans l'objet context pour filtrer les résultats du catalogue et vérifier les disponibilités dans ce magasin spécifique.

Requête (beurre ; retrait)

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "catalog": {
        "query": "salted butter",
        "context": {
          "location": "loc_valley_grocers_chicago_clark"
        }
      }
    }
  }
}

REST

POST /catalog/search HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab05
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "query": "salted butter",
  "context": {
    "location": "loc_valley_grocers_chicago_clark"
  }
}

Réponse (beurre)

Dans tous les scénarios, la réponse contient la meilleure correspondance pour "beurre salé", avec le prix, la disponibilité pour la livraison ou le retrait en fonction du contexte de localisation fourni, et les variantes de taille.

MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.catalog.search": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "products": [
        {
          "id": "prod_butter_valley_dairy",
          "title": "Valley Dairy Salted Butter",
          "description": {
            "plain": "Premium salted butter sticks."
          },
          "price_range": {
            "min": {
              "amount": 299,
              "currency": "USD"
            },
            "max": {
              "amount": 499,
              "currency": "USD"
            }
          },
          "variants": [
            {
              "id": "var_butter_valley_dairy_8oz",
              "title": "Valley Dairy Salted Butter (8 oz)",
              "description": {
                "plain": "Valley Dairy Salted Butter (8 oz) pack."
              },
              "price": {
                "amount": 299,
                "currency": "USD"
              },
              "availability": {
                "status": "in_stock"
              }
            },
            {
              "id": "var_butter_valley_dairy_16oz",
              "title": "Valley Dairy Salted Butter (16 oz)",
              "description": {
                "plain": "Valley Dairy Salted Butter (16 oz) pack."
              },
              "price": {
                "amount": 499,
                "currency": "USD"
              },
              "availability": {
                "status": "in_stock"
              }
            }
          ]
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "products": [
    {
      "id": "prod_butter_valley_dairy",
      "title": "Valley Dairy Salted Butter",
      "description": {
        "plain": "Premium salted butter sticks."
      },
      "price_range": {
        "min": {
          "amount": 299,
          "currency": "USD"
        },
        "max": {
          "amount": 499,
          "currency": "USD"
        }
      },
      "variants": [
        {
          "id": "var_butter_valley_dairy_8oz",
          "title": "Valley Dairy Salted Butter (8 oz)",
          "description": {
            "plain": "Valley Dairy Salted Butter (8 oz) pack."
          },
          "price": {
            "amount": 299,
            "currency": "USD"
          },
          "availability": {
            "status": "in_stock"
          }
        },
        {
          "id": "var_butter_valley_dairy_16oz",
          "title": "Valley Dairy Salted Butter (16 oz)",
          "description": {
            "plain": "Valley Dairy Salted Butter (16 oz) pack."
          },
          "price": {
            "amount": 499,
            "currency": "USD"
          },
          "availability": {
            "status": "in_stock"
          }
        }
      ]
    }
  ]
}

---

Créer un panier

L'utilisateur indique son intention de procéder à l'achat. L'agent compile donc les articles et crée un panier.

Remarque : Les indications de localisation validées lors de la recherche (postal_code, buyer_address_location ou location) sont transmises dans les requêtes d'opération de panier via l'objet context de la même manière que search_catalog. Dans les parcours utilisateur, chaque requête inclut un champ d'indication de localisation arbitraire. Pour savoir comment recevoir d'autres types d'indications de localisation, consultez les opérations search_catalog ou le fichier context.json.

• Opération/Outil : create_cart
• Fonctionnalité : dev.ucp.shopping.cart
• Spécifications de transport : spécification MCP et spécification REST

L'exemple suivant illustre la création d'un panier à l'aide d'un indice de localisation de code postal de livraison ("context": { "postal_code": "60614"}).

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_cart",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "cart": {
        "context": {
          "postal_code": "60614"
        },
        "line_items": [
          {
            "item": {
              "id": "var_butter_valley_dairy_8oz"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_garlic_3pk"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_onion_yellow_single"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_tomatoes_bella_vista_28oz"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_pasta_roma_spaghetti_16oz"
            },
            "quantity": 1
          }
        ]
      }
    }
  }
}

REST

POST /carts HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab06
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "context": {
    "postal_code": "60614"
  },
  "line_items": [
    {
      "item": {
        "id": "var_butter_valley_dairy_8oz"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_garlic_3pk"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_onion_yellow_single"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_tomatoes_bella_vista_28oz"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz"
      },
      "quantity": 1
    }
  ]
}

Réponse

Vous créez le panier de livraison en renvoyant les totaux estimés et un élément continue_url, qui redirige les utilisateurs vers votre processus de paiement pour finaliser la commande (y compris l'adresse de livraison finale, la sélection du créneau horaire et le paiement).

Remarque : Chaque entrée de line_items dans les réponses du panier (create_cart, update_cart, get_cart et cancel_cart) doit inclure item.image_url (un URI d'image de produit, conformément au schéma d'élément UCP) afin que Google puisse afficher les images des produits dans l'UI du panier. Les images doivent mesurer plus de 64 x 64 pixels.

MCP

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.cart": [
            { "version": "2026-08-25" }
          ]
        }
      },
      "id": "cart_chicago_grocery_98765",
      "line_items": [
        {
          "id": "li_butter_01",
          "item": {
            "id": "var_butter_valley_dairy_8oz",
            "title": "Valley Dairy Salted Butter (8 oz)",
            "price": 299,
            "image_url": "https://business.example.com/images/var_butter_valley_dairy_8oz.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }
          ]
        },
        {
          "id": "li_garlic_01",
          "item": {
            "id": "var_garlic_3pk",
            "title": "Garlic (3-Pack)",
            "price": 249,
            "image_url": "https://business.example.com/images/var_garlic_3pk.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "display_text": "Subtotal", "amount": 249 }
          ]
        },
        {
          "id": "li_onion_01",
          "item": {
            "id": "var_onion_yellow_single",
            "title": "Yellow Onion (Single)",
            "price": 79,
            "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "display_text": "Subtotal", "amount": 79 }
          ]
        },
        {
          "id": "li_tomatoes_01",
          "item": {
            "id": "var_tomatoes_bella_vista_28oz",
            "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
            "price": 299,
            "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }
          ]
        },
        {
          "id": "li_pasta_01",
          "item": {
            "id": "var_pasta_roma_spaghetti_16oz",
            "title": "Roma Organics Spaghetti (16 oz)",
            "price": 179,
            "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "display_text": "Subtotal", "amount": 179 }
          ]
        }
      ],
      "currency": "USD",
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 1105 },
        { "type": "total", "display_text": "Total", "amount": 1105 }
      ],
      "continue_url": "https://business.example.com/cart/"
    }
  }
}

REST

HTTP/1.1 201 Created
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        { "version": "2026-08-25" }
      ]
    }
  },
  "id": "cart_chicago_grocery_98765",
  "line_items": [
    {
      "id": "li_butter_01",
      "item": {
        "id": "var_butter_valley_dairy_8oz",
        "title": "Valley Dairy Salted Butter (8 oz)",
        "price": 299,
        "image_url": "https://business.example.com/images/var_butter_valley_dairy_8oz.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }
      ]
    },
    {
      "id": "li_garlic_01",
      "item": {
        "id": "var_garlic_3pk",
        "title": "Garlic (3-Pack)",
        "price": 249,
        "image_url": "https://business.example.com/images/var_garlic_3pk.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 249 }
      ]
    },
    {
      "id": "li_onion_01",
      "item": {
        "id": "var_onion_yellow_single",
        "title": "Yellow Onion (Single)",
        "price": 79,
        "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 79 }
      ]
    },
    {
      "id": "li_tomatoes_01",
      "item": {
        "id": "var_tomatoes_bella_vista_28oz",
        "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
        "price": 299,
        "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }
      ]
    },
    {
      "id": "li_pasta_01",
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz",
        "title": "Roma Organics Spaghetti (16 oz)",
        "price": 179,
        "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "display_text": "Subtotal", "amount": 179 }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    { "type": "subtotal", "display_text": "Subtotal", "amount": 1105 },
    { "type": "total", "display_text": "Total", "amount": 1105 }
  ],
  "continue_url": "https://business.example.com/cart/"
}

---

Mettre à jour le panier

L'utilisateur décide qu'il veut la plaquette de beurre de 500 g au lieu de 250 g. L'agent met à jour le panier pour remplacer l'article. Il effectue un appel update_cart avec l'ID du panier, conserve le contexte de localisation approprié, supprime la plaquette de beurre de 250 g et ajoute celle de 500 g. update_cart est une actualisation complète.

Remarque : Les indications de localisation obtenues lors des opérations de recherche et de catalogue (postal_code, buyer_address_location ou location) sont transmises dans l'objet cart.context de la même manière que celle décrite. Cet exemple utilise une indication de localisation arbitraire.

• Opération/Outil : update_cart
• Fonctionnalité : dev.ucp.shopping.cart
• Spécifications de transport : spécification MCP et spécification REST

L'exemple suivant illustre la mise à jour d'un panier pour le retrait en magasin à l'aide d'une indication de localisation par identifiant de magasin ("cart": { "context": { "location": "loc_valley_grocers_chicago_clark" }, ... }).

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "update_cart",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "id": "cart_chicago_grocery_98765",
      "cart": {
        "context": {
          "location": "loc_valley_grocers_chicago_clark"
        },
        "line_items": [
          {
            "item": {
              "id": "var_butter_valley_dairy_16oz"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_garlic_3pk"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_onion_yellow_single"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_tomatoes_bella_vista_28oz"
            },
            "quantity": 1
          },
          {
            "item": {
              "id": "var_pasta_roma_spaghetti_16oz"
            },
            "quantity": 1
          }
        ]
      }
    }
  }
}

REST

PUT /carts/cart_chicago_grocery_98765 HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab07
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "line_items": [
    {
      "item": {
        "id": "var_butter_valley_dairy_16oz"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_garlic_3pk"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_onion_yellow_single"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_tomatoes_bella_vista_28oz"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz"
      },
      "quantity": 1
    }
  ],
  "context": {
    "location": "loc_valley_grocers_chicago_clark"
  }
}

Réponse

La réponse contient l'état mis à jour du panier. Les totaux sont mis à jour en conséquence.

MCP

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.cart": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "id": "cart_chicago_grocery_98765",
      "line_items": [
        {
          "id": "li_garlic_01",
          "item": {
            "id": "var_garlic_3pk",
            "title": "Garlic (3-Pack)",
            "price": 249,
            "image_url": "https://business.example.com/images/var_garlic_3pk.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 249
            }
          ]
        },
        {
          "id": "li_onion_01",
          "item": {
            "id": "var_onion_yellow_single",
            "title": "Yellow Onion (Single)",
            "price": 79,
            "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 79
            }
          ]
        },
        {
          "id": "li_tomatoes_01",
          "item": {
            "id": "var_tomatoes_bella_vista_28oz",
            "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
            "price": 299,
            "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 299
            }
          ]
        },
        {
          "id": "li_pasta_01",
          "item": {
            "id": "var_pasta_roma_spaghetti_16oz",
            "title": "Roma Organics Spaghetti (16 oz)",
            "price": 179,
            "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 179
            }
          ]
        },
        {
          "id": "li_butter_02",
          "item": {
            "id": "var_butter_valley_dairy_16oz",
            "title": "Valley Dairy Salted Butter (16 oz)",
            "price": 499,
            "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 499
            }
          ]
        }
      ],
      "currency": "USD",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 1305
        },
        {
          "type": "total",
          "display_text": "Total",
          "amount": 1305
        }
      ],
      "continue_url": "https://business.example.com/cart/"
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "id": "cart_chicago_grocery_98765",
  "line_items": [
    {
      "id": "li_garlic_01",
      "item": {
        "id": "var_garlic_3pk",
        "title": "Garlic (3-Pack)",
        "price": 249,
        "image_url": "https://business.example.com/images/var_garlic_3pk.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 249
        }
      ]
    },
    {
      "id": "li_onion_01",
      "item": {
        "id": "var_onion_yellow_single",
        "title": "Yellow Onion (Single)",
        "price": 79,
        "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 79
        }
      ]
    },
    {
      "id": "li_tomatoes_01",
      "item": {
        "id": "var_tomatoes_bella_vista_28oz",
        "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
        "price": 299,
        "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 299
        }
      ]
    },
    {
      "id": "li_pasta_01",
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz",
        "title": "Roma Organics Spaghetti (16 oz)",
        "price": 179,
        "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 179
        }
      ]
    },
    {
      "id": "li_butter_02",
      "item": {
        "id": "var_butter_valley_dairy_16oz",
        "title": "Valley Dairy Salted Butter (16 oz)",
        "price": 499,
        "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 499
        }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 1305
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 1305
    }
  ],
  "continue_url": "https://business.example.com/cart/"
}

Remarque : Si l'indication de localisation change, une reconstruction complète du panier est requise et vous devez à nouveau traiter le panier avec l'indication de localisation mise à jour.

---

Récupérer le panier

get_cart permet de récupérer un panier précédemment créé, par exemple si l'utilisateur démarre une nouvelle session et souhaite continuer à remplir son panier précédent.

• Opération/Outil : get_cart
• Fonctionnalité : dev.ucp.shopping.cart
• Spécifications de transport : spécification MCP et spécification REST

L'exemple suivant illustre la récupération de la session du panier à l'aide de l'ID du panier de l'opération de mise à jour précédente ("id": "cart_chicago_grocery_98765").

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_cart",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "id": "cart_chicago_grocery_98765"
    }
  }
}

REST

GET /carts/cart_chicago_grocery_98765 HTTP/1.1
Host: business.example.com
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab08
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

Réponse

Vous renvoyez l'état actuel de la session de panier demandée.

MCP

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.cart": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "id": "cart_chicago_grocery_98765",
      "line_items": [
        {
          "id": "li_garlic_01",
          "item": {
            "id": "var_garlic_3pk",
            "title": "Garlic (3-Pack)",
            "price": 249,
            "image_url": "https://business.example.com/images/var_garlic_3pk.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 249
            }
          ]
        },
        {
          "id": "li_onion_01",
          "item": {
            "id": "var_onion_yellow_single",
            "title": "Yellow Onion (Single)",
            "price": 79,
            "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 79
            }
          ]
        },
        {
          "id": "li_tomatoes_01",
          "item": {
            "id": "var_tomatoes_bella_vista_28oz",
            "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
            "price": 299,
            "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 299
            }
          ]
        },
        {
          "id": "li_pasta_01",
          "item": {
            "id": "var_pasta_roma_spaghetti_16oz",
            "title": "Roma Organics Spaghetti (16 oz)",
            "price": 179,
            "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 179
            }
          ]
        },
        {
          "id": "li_butter_02",
          "item": {
            "id": "var_butter_valley_dairy_16oz",
            "title": "Valley Dairy Salted Butter (16 oz)",
            "price": 499,
            "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 499
            }
          ]
        }
      ],
      "currency": "USD",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 1305
        },
        {
          "type": "total",
          "display_text": "Total",
          "amount": 1305
        }
      ],
      "continue_url": "https://business.example.com/cart/"
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "id": "cart_chicago_grocery_98765",
  "line_items": [
    {
      "id": "li_garlic_01",
      "item": {
        "id": "var_garlic_3pk",
        "title": "Garlic (3-Pack)",
        "price": 249,
        "image_url": "https://business.example.com/images/var_garlic_3pk.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 249
        }
      ]
    },
    {
      "id": "li_onion_01",
      "item": {
        "id": "var_onion_yellow_single",
        "title": "Yellow Onion (Single)",
        "price": 79,
        "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 79
        }
      ]
    },
    {
      "id": "li_tomatoes_01",
      "item": {
        "id": "var_tomatoes_bella_vista_28oz",
        "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
        "price": 299,
        "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 299
        }
      ]
    },
    {
      "id": "li_pasta_01",
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz",
        "title": "Roma Organics Spaghetti (16 oz)",
        "price": 179,
        "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 179
        }
      ]
    },
    {
      "id": "li_butter_02",
      "item": {
        "id": "var_butter_valley_dairy_16oz",
        "title": "Valley Dairy Salted Butter (16 oz)",
        "price": 499,
        "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 499
        }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 1305
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 1305
    }
  ],
  "continue_url": "https://business.example.com/cart/"
}

---

Rechercher des lieux

Le backend UCP ne met pas en cache les informations de localisation, mais uniquement les identifiants de localisation que vous lui avez fournis. Par conséquent, lookup_locations est appelé chaque fois que l'UI du panier doit être présentée à l'utilisateur (sauf si l'indication de localisation est un élément postal_code) pour obtenir l'adresse de livraison ou l'adresse de retrait en magasin. Les adresses de magasins et de livraison peuvent être incluses dans le tableau ids de la requête, et la réponse doit inclure le tableau locations ou buyer_address_locations approprié.

• Opération/Outil : lookup_locations
• Fonctionnalité : dev.ucp.common.location.lookup
• Spécifications de transport : spécification MCP et spécification REST

Adresse des magasins

L'exemple suivant illustre la recherche d'une adresse de retrait en magasin par son identifiant ("ids": ["loc_valley_grocers_chicago_clark"]).

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "lookup_locations",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "location": {
        "ids": [
          "loc_valley_grocers_chicago_clark"
        ]
      }
    }
  }
}

REST

POST /locations/lookup HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab09
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "ids": [
    "loc_valley_grocers_chicago_clark"
  ]
}

Réponse

Vous renvoyez les informations validées sur l'adresse de retrait en magasin dans le tableau locations, y compris les métadonnées de corrélation inputs requises.

MCP

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.lookup": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [
        {
          "id": "loc_valley_grocers_chicago_clark",
          "inputs": [
            {
              "id": "loc_valley_grocers_chicago_clark"
            }
          ],
          "name": "Valley Grocers - Lincoln Park",
          "address": {
            "street_address": "2200 N Clark St",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.lookup": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [
    {
      "id": "loc_valley_grocers_chicago_clark",
      "inputs": [
        {
          "id": "loc_valley_grocers_chicago_clark"
        }
      ],
      "name": "Valley Grocers - Lincoln Park",
      "address": {
        "street_address": "2200 N Clark St",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    }
  ]
}

---

Adresses de livraison de l'acheteur

L'exemple suivant illustre la recherche d'une adresse de livraison enregistrée par l'acheteur à l'aide de son identifiant ("ids": ["addr_user_home_01"]).

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "lookup_locations",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        }
      },
      "location": {
        "ids": [
          "addr_user_home_01"
        ]
      }
    }
  }
}

REST

POST /locations/lookup HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab10
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"

{
  "ids": [
    "addr_user_home_01"
  ]
}

Réponse

Vous renvoyez l'adresse de livraison validée dans le tableau buyer_address_locations.

MCP

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.common.location.lookup": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "locations": [],
      "buyer_address_locations": [
        {
          "id": "addr_user_home_01",
          "inputs": [
            {
              "id": "addr_user_home_01"
            }
          ],
          "name": "Home",
          "address": {
            "street_address": "2200 N Clark St, Apt 4B",
            "address_locality": "Chicago",
            "address_region": "IL",
            "address_country": "US",
            "postal_code": "60614"
          }
        }
      ]
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.common.location.lookup": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "locations": [],
  "buyer_address_locations": [
    {
      "id": "addr_user_home_01",
      "inputs": [
        {
          "id": "addr_user_home_01"
        }
      ],
      "name": "Home",
      "address": {
        "street_address": "2200 N Clark St, Apt 4B",
        "address_locality": "Chicago",
        "address_region": "IL",
        "address_country": "US",
        "postal_code": "60614"
      }
    }
  ]
}

---

Annuler le panier

cancel_cart est appelé si l'utilisateur exprime l'intention de recommencer avec une autre recette ou s'il souhaite vider l'intégralité de son panier. L'appel de cancel_cart doit déclencher une logique métier de votre côté pour mettre fin immédiatement à la session du panier ou l'invalider, de sorte que l'ID du panier ne soit plus disponible. Si vous conservez un ID de panier persistant par utilisateur de votre côté, vous devez créer des ID de panier lors des opérations create_cart et maintenir les correspondances entre ces ID de panier créés par Google et l'ID de panier persistant unique de l'utilisateur pendant la durée de vie de ces paniers.

• Opération/Outil : cancel_cart
• Fonctionnalité : dev.ucp.shopping.cart
• Spécifications de transport : spécification MCP et spécification REST

L'exemple suivant illustre l'annulation de la session de panier existante à l'aide de son ID de panier ("id": "cart_chicago_grocery_98765").

Demande

MCP

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "cancel_cart",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/grocery-agent.json"
        },
        "idempotency-key": "660e8400-e29b-41d4-a716-446655440001"
      },
      "id": "cart_chicago_grocery_98765"
    }
  }
}

REST

POST /carts/cart_chicago_grocery_98765/cancel HTTP/1.1
Host: business.example.com
Content-Type: application/json
Request-Id: 8ef9b0c2-78d1-4e4b-91c2-3e2ef0d3ab11
UCP-Agent: profile="https://platform.example/profiles/grocery-agent.json"
Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001

{}

Réponse

Vous annulez la session du panier et renvoyez l'état du panier avant la suppression.

Remarque : Les opérations ultérieures faisant référence à un ID de panier annulé doivent renvoyer une erreur not_found.

MCP

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.cart": [
            {
              "version": "2026-08-25"
            }
          ]
        }
      },
      "id": "cart_chicago_grocery_98765",
      "line_items": [
        {
          "id": "li_garlic_01",
          "item": {
            "id": "var_garlic_3pk",
            "title": "Garlic (3-Pack)",
            "price": 249,
            "image_url": "https://business.example.com/images/var_garlic_3pk.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 249
            }
          ]
        },
        {
          "id": "li_onion_01",
          "item": {
            "id": "var_onion_yellow_single",
            "title": "Yellow Onion (Single)",
            "price": 79,
            "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 79
            }
          ]
        },
        {
          "id": "li_tomatoes_01",
          "item": {
            "id": "var_tomatoes_bella_vista_28oz",
            "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
            "price": 299,
            "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 299
            }
          ]
        },
        {
          "id": "li_pasta_01",
          "item": {
            "id": "var_pasta_roma_spaghetti_16oz",
            "title": "Roma Organics Spaghetti (16 oz)",
            "price": 179,
            "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 179
            }
          ]
        },
        {
          "id": "li_butter_02",
          "item": {
            "id": "var_butter_valley_dairy_16oz",
            "title": "Valley Dairy Salted Butter (16 oz)",
            "price": 499,
            "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 499
            }
          ]
        }
      ],
      "currency": "USD",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 1305
        },
        {
          "type": "total",
          "display_text": "Total",
          "amount": 1305
        }
      ],
      "continue_url": "https://business.example.com/cart/"
    }
  }
}

REST

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-08-25",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-08-25"
        }
      ]
    }
  },
  "id": "cart_chicago_grocery_98765",
  "line_items": [
    {
      "id": "li_garlic_01",
      "item": {
        "id": "var_garlic_3pk",
        "title": "Garlic (3-Pack)",
        "price": 249,
        "image_url": "https://business.example.com/images/var_garlic_3pk.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 249
        }
      ]
    },
    {
      "id": "li_onion_01",
      "item": {
        "id": "var_onion_yellow_single",
        "title": "Yellow Onion (Single)",
        "price": 79,
        "image_url": "https://business.example.com/images/var_onion_yellow_single.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 79
        }
      ]
    },
    {
      "id": "li_tomatoes_01",
      "item": {
        "id": "var_tomatoes_bella_vista_28oz",
        "title": "Bella Vista Organic Whole Peeled Tomatoes (28 oz Can)",
        "price": 299,
        "image_url": "https://business.example.com/images/var_tomatoes_bella_vista_28oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 299
        }
      ]
    },
    {
      "id": "li_pasta_01",
      "item": {
        "id": "var_pasta_roma_spaghetti_16oz",
        "title": "Roma Organics Spaghetti (16 oz)",
        "price": 179,
        "image_url": "https://business.example.com/images/var_pasta_roma_spaghetti_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 179
        }
      ]
    },
    {
      "id": "li_butter_02",
      "item": {
        "id": "var_butter_valley_dairy_16oz",
        "title": "Valley Dairy Salted Butter (16 oz)",
        "price": 499,
        "image_url": "https://business.example.com/images/var_butter_valley_dairy_16oz.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 499
        }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 1305
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 1305
    }
  ],
  "continue_url": "https://business.example.com/cart/"
}

---

Profil et découverte

Les informations sur la négociation de profil et de découverte, y compris les définitions d'extension de fournisseur, sont en cours de développement.

Gestion des erreurs

Les erreurs sont gérées comme décrit dans Gestion des erreurs UCP et Erreurs de résultat métier UCP. Les erreurs de résultat métier associées ici sont documentées dans la fonctionnalité de paiement, mais le concept est universel dans l'UCP.

Remarque : Si l'état n'est pas défini dans la réponse, la valeur par défaut est "success". En cas d'erreurs liées aux résultats métier, vous devez définir l'état sur "error".

Niveaux d'accès UCP requis

Ces niveaux d'accès sont requis pour activer les fonctionnalités UCP.

• dev.ucp.shopping.cart:manage
• dev.ucp.shopping.catalog.search:read
• dev.ucp.shopping.catalog.lookup:read
• dev.ucp.common.location.lookup:read
• dev.ucp.common.location.search:read
• dev.ucp.shopping.order:manage
• dev.ucp.shopping.checkout:manage