ap2-cart-mandate

AP2 Cart Mandate

Before writing code

Fetch live docs:

1. Fetch https://ap2-protocol.org/specification/ for the Cart Mandate schema
2. Web-search site:github.com google-agentic-commerce AP2 src/ap2/types mandate for the Python type definitions
3. Web-search site:github.com google-agentic-commerce AP2 samples cart mandate for sample implementations
4. Fetch https://ap2-protocol.org/topics/core-concepts/ for Cart Mandate conceptual details

Conceptual Architecture

What the Cart Mandate Is

The Cart Mandate is the primary VDC for human-present transactions. It captures explicit user authorization for a specific set of items at specific prices, cryptographically binding the user's identity and consent to the exact transaction details.

Who Creates It

The Merchant Endpoint creates and signs the Cart Mandate after receiving an Intent Mandate from the Shopping Agent. The merchant's signature guarantees fulfillment of the specified items at the specified prices.

Who Signs It

Two signatures are required:

1. Merchant signature — Entity-level (not agent-level) guarantee of fulfillment
2. User signature — Hardware-backed device key with in-session authentication

Cart Mandate Structure

A CartMandate has two parts: contents (CartContents) and merchant_authorization (a JWT).

CartContents fields: id, user_cart_confirmation_required, payment_request (W3C PaymentRequest), cart_expiry, merchant_name.

Based on the specification, key fields include:

{
  "contents": {
    "id": "cart_identifier",
    "user_cart_confirmation_required": true,
    "payment_request": {
      "method_data": [
        {
          "supportedMethods": "https://processor.example.com/pay",
          "data": { ... }
        }
      ],
      "details": {
        "id": "order_id",
        "displayItems": [
          { "label": "Product Name", "amount": { "currency": "USD", "value": "29.99" } }
        ],
        "total": {
          "label": "Total",
          "amount": { "currency": "USD", "value": "29.99" }
        },
        "shipping_options": null
      },
      "options": {
        "requestPayerName": true,
        "requestShipping": true,
        "requestPayerEmail": false,
        "requestPayerPhone": false
      }
    },
    "cart_expiry": "2025-09-01T13:00:00Z",
    "merchant_name": "Example Merchant"
  },
  "merchant_authorization": "<base64url-header>..<base64url-signature>"
}