Trusteed Demo Store

ucp_complete_checkout

Idempotent

Complete a UCP checkout session. Transitions to 'completed' status. Idempotent — safe to retry with the same idempotency_key. Use ONLY for a checkout session created with ucp_create_checkout (Universal Commerce Protocol); for the standard flow (create_cart, preview_checkout, complete_checkout) do not call this tool. For a cart built with create_cart use complete_checkout. PAYMENT MANDATE: this tool also requires one. Send it as the payment_mandate argument if your client cannot set headers, or as an X-Payment-Mandate header. It must carry mandate_id, max_amount_cents, currency, exp, sub, aud. Two of these are rejected outright if guessed: exp is an INTEGER of Unix seconds (not an ISO 8601 date), and aud is this store's slug (the one in the URL you are calling, not a domain). Its currency must match the cart's currency. Demo Store enforces max_amount_cents against the cart total; a real merchant may only observe that boundary, so enforce the buyer's limit in the agent too. The mandate is a spending cap you declare to limit yourself — it authorises nothing and does not prove the buyer's consent — and its sub must be the identity you authenticate as. max_amount_cents is the spending limit the person you are buying for gave you: ask them if they gave none. Checkout guide: read the MCP resource trusteed://guides/checkout.

Input Schema

TableJSON Schema

Name	Required	Description
`ap2`	No	AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization.
`meta`	No	UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters).
`buyer`	No	Buyer name and email, needed to request the approval link.
`payment`	No	UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token.
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`checkout_id`	Yes	UCP checkout session ID (valid UUID)
`x402_payload`	No	x402: signed payment for the server offer (omit to get it).
`payment_option`	No	Payment method THE PERSON chose, when preview_checkout returned payment_options. Ask the person; never choose for them. Card numbers and wallet keys are never sent here: the person approves (and, with own_wallet, signs) on the approval page.
`idempotency_key`	Yes	REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation.
`payment_handler`	No	Payment handler the store profile publishes. Omit for default.
`payment_mandate`	No	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.
`shared_payment_token`	No	Stripe Shared Payment Token (spt_…) granted by the buyer's agent wallet for payment_method=ACP. Issued by Stripe, scoped to this merchant, amount and currency, and consumed when used: it can be charged once. Only honoured when this deployment enables native ACP settlement.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes
`label`	No
`intent`	No
`status`	Yes
`totals`	Yes
`currency`	Yes
`next_step`	No	Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method.
`created_at`	Yes
`expires_at`	No	ISO-8601 UTC instant at which this checkout SESSION stops being usable. It is not a stock reservation and not a price guarantee.
`extensions`	No	`warnings[]` with `code`, `message`, `severity`.
`line_items`	Yes
`updated_at`	Yes
`fulfillment`	No
`next_action`	No	Only when a person must approve or pay: `url`, `kind`, `retry`.
`approval_url`	No
`idempotency_key`	No
`payment_options`	No	When present, ask the person which option they want; never choose for them.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 15, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Unique key to prevent duplicate completions. Generate once per attempt."New value: +"REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."

addedInput schema / properties / idempotency_key / maxLength
```
Added value: +128
```
addedInput schema / properties / idempotency_key / pattern
```
Added value: +"^[A-Za-z0-9._:/-]{1,128}$"
```

addedOutput schema / properties / next_step / description

Added value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method."

First observedOct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare idempotentHint=true, but the description goes well beyond them: it discloses that a payment mandate is required, the exact six fields it must carry, the two commonly-guessed fields that are rejected outright (exp as Unix integer, aud as store slug), the currency-match requirement, and the semantic framing that the mandate is a self-imposed spending cap, not buyer consent. This is unusually rich behavioral context for a mutation tool.

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 core purpose and routing before the mandate detail, and labeled sections (PAYMENT MANDATE) aid scanning. It is somewhat verbose and the mandate field explanations are repeated between the top-level paragraph and the schema descriptions, which dilutes conciseness without harming usability.

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?

Given an output schema exists, the description needn't cover return values. It covers the prerequisites, alternatives, payment mandate requirements, authentication identity, and idempotency behavior — everything an agent needs to invoke this correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 12 parameters including the mandate object fields. The description largely restates the mandate fields (mandate_id, max_amount_cents, currency, exp, sub, aud) that the schema already defines. It adds some value by stressing exp must be an integer and aud is a slug, and the idempotency_key-as-argument nuance, but this is mostly duplicative of the schema.

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?

States a specific verb and resource ('Complete a UCP checkout session') plus the resulting state transition ('Transitions to completed status'). It explicitly distinguishes itself from the sibling complete_checkout by scoping itself to ucp_create_checkout sessions, so an agent can tell them apart without opening a 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?

Gives explicit when-to-use ('ONLY for a checkout session created with ucp_create_checkout') and when-not ('for the standard flow ... do not call this tool') with the named alternative ('use complete_checkout'). It also names the prerequisite prerequisite flow and points to the checkout guide resource.

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

All Trusteed Demo Store 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?