Trusteed Agentic Commerce

preview_checkout

Preview the complete order summary before payment. Advances the session to ready-for-payment state. If you only need the price, call quote_checkout instead: it computes the same total without advancing the session or opening an approval.

PREFER THE CART CARD: if there is an interactive card for this cart, let it compute and show the summary instead of calling this tool yourself — it keeps the flow in one card. Checkout guide: read the MCP resource trusteed://guides/checkout. CREDENTIAL: this store needs one. Call the create_sandbox_key tool first (it is in this tool list and needs no credential), then pass the key you get back as the agent_key argument — or as an Authorization: Bearer header if your client can set headers. Do not ask a person to log in: there is no human login for this store.

Input Schema

Name	Required	Description
`cart_id`	Yes	Cart session ID returned by create_cart
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`payment_mandate`	No	Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header.

Output Schema

Name	Required	Description
`items`	Yes
`status`	Yes
`currency`	Yes
`next_step`	No
`tax_cents`	Yes
`expires_at`	No
`store_name`	Yes
`tax_status`	Yes
`total_note`	Yes
`approval_id`	No
`total_cents`	Yes
`approval_url`	No
`discount_cents`	Yes
`shipping_cents`	Yes
`shipping_title`	No
`subtotal_cents`	Yes
`total_is_final`	Yes
`payment_options`	No
`shipping_source`	No
`next_step_message`	No
`expires_in_seconds`	No	Whole seconds left on this checkout SESSION at response time (0 when already past). It is not a stock reservation and not a price guarantee.
`approval_status_url`	No
`checkout_session_id`	Yes
`shipping_authoritative`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

changedInput schema / properties / payment_mandate / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {
-      "aud": {
-        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
-        "maxLength": 256,
-        "minLength": 1,
-        "type": "string"
-      },
-      "currency": {
-        "description": "Three-letter currency code; must match the cart's currency.",
-        "maxLength": 3,
-        "minLength": 3,
-        "type": "string"
-      },
-      "exp": {
-        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
-        "exclusiveMinimum": 0,
-        "type": "integer"
-      },
-      "mandate_id": {
-        "description": "Your identifier for this mandate.",
-        "maxLength": 128,
-        "minLength": 1,
-        "type": "string"
-      },
-      "max_amount_cents": {
-        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
-        "exclusiveMinimum": 0,
-        "type": "integer"
-      },
-      "sub": {
-        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
-        "maxLength": 256,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "mandate_id",
-      "max_amount_cents",
-      "currency",
-      "exp",
-      "sub",
-      "aud"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "string"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "type": "object"
+  },
+  {
+    "type": "string"
+  }
+]

changedInput schema / properties / payment_mandate / description

Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header."

Changed1 schema field changedOct 14, 2026

changedInput schema / properties / payment_mandate / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "type": "object"
-  },
-  {
-    "type": "string"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "aud": {
+        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
+        "maxLength": 256,
+        "minLength": 1,
+        "type": "string"
+      },
+      "currency": {
+        "description": "Three-letter currency code; must match the cart's currency.",
+        "maxLength": 3,
+        "minLength": 3,
+        "type": "string"
+      },
+      "exp": {
+        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
+        "exclusiveMinimum": 0,
+        "type": "integer"
+      },
+      "mandate_id": {
+        "description": "Your identifier for this mandate.",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      },
+      "max_amount_cents": {
+        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
+        "exclusiveMinimum": 0,
+        "type": "integer"
+      },
+      "sub": {
+        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
+        "maxLength": 256,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "mandate_id",
+      "max_amount_cents",
+      "currency",
+      "exp",
+      "sub",
+      "aud"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "string"
+  }
+]

Changed1 schema field changedOct 13, 2026
- addedOutput schema / properties / payment_options / items / properties / charges_without_approval
```
Added value: +{
+  "const": true,
+  "type": "boolean"
+}
```

Changed3 schema fields changedOct 13, 2026

changedOutput schema / properties / payment_options / items / properties / id / enum

Previous value: -[
-  "demo_card",
-  "demo_wallet",
-  "own_wallet",
-  "merchant_card",
-  "kyapay"
-]New value: +[
+  "demo_card",
+  "demo_wallet",
+  "own_wallet",
+  "merchant_card",
+  "paypal",
+  "kyapay"
+]

changedOutput schema / properties / payment_options / items / properties / rail / enum

Previous value: -[
-  "stripe",
-  "x402",
-  "kyapay"
-]New value: +[
+  "stripe",
+  "x402",
+  "kyapay",
+  "paypal"
+]

changedOutput schema / properties / payment_options / items / properties / reason_unavailable / enum

Previous value: -[
-  "coming_soon",
-  "not_enabled",
-  "currency_not_supported"
-]New value: +[
+  "coming_soon",
+  "not_enabled",
+  "currency_not_supported",
+  "unsupported_on_this_tool"
+]

Changed1 schema field changedOct 10, 2026

addedOutput schema / properties / expires_in_seconds

Added value: +{
+  "description": "Whole seconds left on this checkout SESSION at response time (0 when already past). It is not a stock reservation and not a price guarantee.",
+  "minimum": 0,
+  "type": "integer"
+}

Changed1 schema field changedOct 10, 2026

changedOutput schema / properties / payment_options / items / properties / reason_unavailable / enum

Previous value: -[
-  "coming_soon",
-  "not_enabled"
-]New value: +[
+  "coming_soon",
+  "not_enabled",
+  "currency_not_supported"
+]

Changed1 schema field changedOct 5, 2026

changedOutput schema / properties / payment_options / items / properties / id / enum

Previous value: -[
-  "demo_card",
-  "demo_wallet",
-  "own_wallet",
-  "kyapay"
-]New value: +[
+  "demo_card",
+  "demo_wallet",
+  "own_wallet",
+  "merchant_card",
+  "kyapay"
+]

Changed3 schema fields changedSep 28, 2026

addedOutput schema / properties / next_step

Added value: +{
+  "const": "ask_user_payment_method",
+  "type": "string"
+}

addedOutput schema / properties / next_step_message
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / payment_options

Added value: +{
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "available": {
+        "type": "boolean"
+      },
+      "funding_source": {
+        "anyOf": [
+          {
+            "enum": [
+              "platform_test_card",
+              "platform_test_wallet",
+              "buyer_wallet"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "id": {
+        "enum": [
+          "demo_card",
+          "demo_wallet",
+          "own_wallet",
+          "kyapay"
+        ],
+        "type": "string"
+      },
+      "label": {
+        "type": "string"
+      },
+      "rail": {
+        "enum": [
+          "stripe",
+          "x402",
+          "kyapay"
+        ],
+        "type": "string"
+      },
+      "reason_unavailable": {
+        "enum": [
+          "coming_soon",
+          "not_enabled"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "label",
+      "rail",
+      "funding_source",
+      "available"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed6 schema fields changedSep 26, 2026
- addedOutput schema / properties / approval_id
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / approval_status_url
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / approval_url
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / expires_at
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / status / const
```
Removed value: -"READY_FOR_PAYMENT"
```
- addedOutput schema / properties / status / enum
```
Added value: +[
+  "READY_FOR_PAYMENT",
+  "PENDING_APPROVAL"
+]
```

Changed5 schema fields changedSep 24, 2026

addedOutput schema / properties / tax_cents
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / tax_status

Added value: +{
+  "enum": [
+    "included",
+    "not_calculated"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / total_is_final
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / total_note
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "checkout_session_id",
-  "store_name",
-  "items",
-  "subtotal_cents",
-  "shipping_cents",
-  "discount_cents",
-  "total_cents",
-  "currency",
-  "status"
-]New value: +[
+  "checkout_session_id",
+  "store_name",
+  "items",
+  "subtotal_cents",
+  "shipping_cents",
+  "discount_cents",
+  "total_cents",
+  "currency",
+  "tax_cents",
+  "tax_status",
+  "total_is_final",
+  "total_note",
+  "status"
+]

Changed1 schema field changedSep 24, 2026

changedInput schema / properties / payment_mandate / description

Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (your agent id) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."

Changed2 schema fields changedSep 22, 2026

addedOutput schema / properties / shipping_authoritative
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / shipping_source

Added value: +{
+  "enum": [
+    "platform",
+    "merchant_policy",
+    "estimated"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 21, 2026

changedInput schema / properties / payment_mandate / description

Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (your agent id) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). Use this when your client cannot set an `X-Payment-Mandate` header."

Changed2 schema fields changedSep 20, 2026

addedInput schema / properties / agent_key

Added value: +{
+  "description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.",
+  "type": "string"
+}

addedInput schema / properties / payment_mandate

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "type": "object"
+    },
+    {
+      "type": "string"
+    }
+  ],
+  "description": "Payment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."
+}

Changed3 schema fields changedSep 17, 2026
- changedInput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / items / items / additionalProperties
```
Previous value: -falseNew value: +true
```

Changed1 schema field changedSep 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "checkout_session_id": {
+      "type": "string"
+    },
+    "currency": {
+      "type": "string"
+    },
+    "discount_cents": {
+      "type": "number"
+    },
+    "items": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "line_price": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "quantity": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "name",
+          "quantity",
+          "line_price"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "shipping_cents": {
+      "type": "number"
+    },
+    "shipping_title": {
+      "type": "string"
+    },
+    "status": {
+      "const": "READY_FOR_PAYMENT",
+      "type": "string"
+    },
+    "store_name": {
+      "type": "string"
+    },
+    "subtotal_cents": {
+      "type": "number"
+    },
+    "total_cents": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "checkout_session_id",
+    "store_name",
+    "items",
+    "subtotal_cents",
+    "shipping_cents",
+    "discount_cents",
+    "total_cents",
+    "currency",
+    "status"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedAug 24, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties

Added value: +{
+  "cart_id": {
+    "description": "Cart session ID returned by create_cart",
+    "type": "string"
+  }
+}

addedInput schema / required
```
Added value: +[
+  "cart_id"
+]
```

Changed5 schema fields changedJul 10, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedInput schema / additionalProperties
```
Removed value: -false
```

removedInput schema / properties

Removed value: -{
-  "cart_id": {
-    "description": "Cart session ID returned by create_cart",
-    "type": "string"
-  }
-}

removedInput schema / required
```
Removed value: -[
-  "cart_id"
-]
```

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "checkout_session_id": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "discount_cents": {
-      "type": "number"
-    },
-    "items": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "line_price": {
-            "type": "number"
-          },
-          "name": {
-            "type": "string"
-          },
-          "quantity": {
-            "type": "number"
-          }
-        },
-        "required": [
-          "name",
-          "quantity",
-          "line_price"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "shipping_cents": {
-      "type": "number"
-    },
-    "shipping_title": {
-      "type": "string"
-    },
-    "status": {
-      "const": "READY_FOR_PAYMENT",
-      "type": "string"
-    },
-    "store_name": {
-      "type": "string"
-    },
-    "subtotal_cents": {
-      "type": "number"
-    },
-    "total_cents": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "checkout_session_id",
-    "store_name",
-    "items",
-    "subtotal_cents",
-    "shipping_cents",
-    "discount_cents",
-    "total_cents",
-    "currency",
-    "status"
-  ],
-  "type": "object"
-}New value: +null

First observedApr 28, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description is consistent with them while adding context they cannot carry: it advances the session to ready-for-payment, opens an approval, and requires a credential obtained via create_sandbox_key rather than a human login. This is exactly the kind of state-change and auth disclosure annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the state-change warning, then routing, then credential mechanics. It is denser than average and the bolded cart-card paragraph plus the credential paragraph add length, but each carries actionable routing or auth information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. Between the stated state transition, the alternative tool, the credential provisioning path, and the guide resource, an agent has everything needed to invoke this correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema descriptions for cart_id, agent_key, and payment_mandate are already detailed, so the baseline is 3. The description nonetheless adds sequencing value the schema lacks: it tells the agent to call create_sandbox_key first (which needs no credential) and that the key may be passed as the agent_key argument or an Authorization: Bearer header.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource (preview the complete order summary before payment) and immediately scopes it against the sibling that does something superficially similar, quote_checkout. An agent can distinguish it from quote_checkout, complete_checkout, and get_checkout_state without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use (before payment), explicit when-not (use quote_checkout if you only need the price, because this tool advances the session and opens an approval), a stated preference for the cart card, and a pointer to the checkout guide resource. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Trusteed Agentic Commerce tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?