Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
OAuth 2.1 bearer token. Discovery via /.well-known/oauth-protected-resource (RFC 9728). Public read tools work without auth; checkout tools require Bearer.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Apply a discount or promo code to the cart. 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.
Cart session ID
Set to 'ucp_identity' to apply a loyalty discount derived from a UCP identity token instead of a promo code.
Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
Discount or promo code to apply (required unless source is ucp_identity)
UCP identity bearer token (required when source is ucp_identity).
REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Tool list last changed Oct 25, 2026.
Apply a discount or promo code to the cart. 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.
| Argument | Type | Description |
|---|---|---|
| source | string | Set to 'ucp_identity' to apply a loyalty discount derived from a UCP identity token instead of a promo code. |
| cart_id* | string | Cart session ID |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| discount_code | string | Discount or promo code to apply (required unless source is ucp_identity) |
| identity_token | string | UCP identity bearer token (required when source is ucp_identity). |
| idempotency_key | string | REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"source": {
"type": "string",
"const": "ucp_identity",
"description": "Set to 'ucp_identity' to apply a loyalty discount derived from a UCP identity token instead of a promo code."
},
"cart_id": {
"type": "string",
"description": "Cart session ID"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"discount_code": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "Discount or promo code to apply (required unless source is ucp_identity)"
},
"identity_token": {
"type": "string",
"maxLength": 4096,
"minLength": 1,
"description": "UCP identity bearer token (required when source is ucp_identity)."
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
}
},
"additionalProperties": false
}List all product categories in Demo Store with product counts.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": true
}Compare 2 to 5 products side-by-side with normalized attribute table and best-value recommendation.
| Argument | Type | Description |
|---|---|---|
| product_ids* | array | Array of product IDs to compare (2-5) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"product_ids"
],
"properties": {
"product_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 5,
"minItems": 2,
"description": "Array of product IDs to compare (2-5)"
}
},
"additionalProperties": true
}Complete the purchase. Provide buyer.name and buyer.email from the conversation before opening approval; ask in chat if either is missing. The approval page only reviews these details. PREFER THE CART CARD: if there is an interactive card for this cart, let the buyer confirm and (when the store offers a choice) pick the payment method there — including retrying after a declined payment or switching method — instead of calling this tool yourself. Each call you make here opens a new card in the transcript instead of updating the one already open. Only call it yourself when there is no interactive card or the buyer explicitly asks you to complete it in chat. Idempotent — replay is keyed on checkout_session_id: any retry against a session that already has an order returns that same order (COMPLETED or PENDING_EXTERNAL_CONFIRMATION) without re-charging. The provided idempotency_key is recorded on the session for audit and short-circuits a repeated call with the same key. If the response has status PENDING_EXTERNAL_CONFIRMATION, no purchase has completed yet: read `order_placed` and `next_action` — a person has to approve or pay at its `url`; `next_action` says whether calling again with the same checkout_session_id and idempotency_key can read the outcome. KYAPAY (payment_method=KYAPAY or a kyapay_token): charging with KYApay is not available. KYApay is identity verification here, not a payment rail, so the call is rejected with PAYMENT_METHOD_NOT_CONFIGURED before anything is charged or written; use another payment method. The Skyfire KYA token serves identity on the REST API, not payment in this tool. On demo-store the approval step records a confirmation but does not verify that a human gave it. PAYMENT MANDATE: this tool also requires one, issued by the platform, not written by you. Call `preview_checkout` for this cart, open the `approval_url` it returns, poll `approval_status_url` with your agent credential, and send the mandate you receive as the `payment_mandate` argument or an `X-Payment-Mandate` header. The approval is bound to your agent credential and the cart; it does not verify that a person was present. 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.
Create a shopping cart in Demo Store. Returns a cart_id. Pass it as cart_id to get_shipping_rates, select_shipping_option, apply_discount and preview_checkout; complete_checkout and get_trust_receipt take the same value as checkout_session_id. KYA IDENTITY: a Skyfire kya token has no effect on this tool (it grants no trust boost here); KYA identity applies to the REST agent API (`Authorization: Bearer`), not to the MCP tools. 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.
| Argument | Type | Description |
|---|---|---|
| items* | array | Items to add to cart |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| agent_token | string | JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. A malformed token fails with AGENT_TOKEN_INVALID on any platform. On Shopify stores Trusteed also verifies the signature on receipt against a registered key that must belong to the calling agent (otherwise AGENT_TOKEN_INVALID and no cart is created), and the checkout Function verifies it again offline at payment. On other platforms Trusteed checks its structure only and forwards it to the store. |
| display_context | string | Agent display capability: webview (browser) or headless |
Get a temporary sandbox credential for this demo store, valid 24h. Present it as an `Authorization: Bearer` header, or — when your client cannot set headers — as the `agent_key` argument of the checkout tools. Payments here are simulated: this credential settles nothing and works only on the demo store. No human login is involved at any point.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": true
}Read the current state of a cart created with create_cart: status, lines, totals, selected shipping, when it was previewed, its order if one exists and a pointer to get_trust_receipt. Read-only: it changes nothing and does not open any approval. Use it to resume a purchase; for UCP checkouts use ucp_get_checkout. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| cart_id* | string | The cart id returned by create_cart (the checkout session id, a valid UUID). |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"cart_id": {
"type": "string",
"description": "The cart id returned by create_cart (the checkout session id, a valid UUID)."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
}
},
"additionalProperties": true
}Get the complete profile — trust score, policies, compliance, and protocol support — of the merchant this MCP endpoint belongs to. Takes NO parameters: the merchant is fixed by which store's /:storeSlug/mcp endpoint you connected to, not by an argument. To read a different merchant's profile, call this same tool on that merchant's own endpoint instead.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": true
}Get a SUMMARY of a specific page on Trusteed: its title, description, keywords, related tools and the link to the full page. It returns a summary, not the full page text: read the linked URL when the whole page is needed. `content_scope` says what came back. Pass the page slug (e.g. 'for-agents', 'pricing', 'blog') or a blog post slug (returns its excerpt). Use get_site_map first to discover available slugs. Pass page='blog' to list all blog posts.
| Argument | Type | Description |
|---|---|---|
| page* | string | Page slug (e.g. 'for-agents', 'pricing', 'trust') or blog post slug. Use 'blog' to list all blog posts. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"page"
],
"properties": {
"page": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Page slug (e.g. 'for-agents', 'pricing', 'trust') or blog post slug. Use 'blog' to list all blog posts."
}
},
"additionalProperties": true
}Get detailed information about a specific product in Demo Store, including all variants, sizes, colors, and availability.
| Argument | Type | Description |
|---|---|---|
| product_id* | string | Product ID — use the `id` field returned by search_products or nlweb_ask (e.g. 'prod-001'). Do not invent IDs. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"product_id"
],
"properties": {
"product_id": {
"type": "string",
"description": "Product ID — use the `id` field returned by search_products or nlweb_ask (e.g. 'prod-001'). Do not invent IDs."
}
},
"additionalProperties": true
}Get available shipping rates for the cart. Requires shipping_address — pass it in the call. If the buyer requests the cheapest option, use cheapest_shipping_handle when non-null; it is null when rates cannot be compared in the cart currency. Rates marked authoritative=false are estimates, not the final charge. PREFER THE CART CARD: if create_cart returned an interactive card (the buyer can see and click it), let them enter the address and pick shipping there instead of calling this tool yourself — each top-level call you make here opens a new card in the transcript instead of updating the one already open. Only call it yourself when there is no interactive card (text-only client) or the buyer explicitly asks you to handle it in chat. 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.
| Argument | Type | Description |
|---|---|---|
| cart_id* | string | Cart session ID returned by create_cart |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| shipping_address | object | Destination address. Required: this tool does not prompt for it. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"cart_id": {
"type": "string",
"description": "Cart session ID returned by create_cart"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"shipping_address": {
"type": "object",
"required": [
"address1",
"city",
"country_code",
"zip"
],
"properties": {
"zip": {
"type": "string",
"description": "Postal / ZIP code exactly as written, keeping leading zeros (e.g. \"08001\")"
},
"city": {
"type": "string",
"description": "City"
},
"address1": {
"type": "string",
"description": "Street name and number, plus flat/door if any (e.g. \"Calle Mayor 1, 2B\")"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code, two letters (e.g. ES, US, CA). Never the country name."
},
"province_code": {
"type": "string",
"description": "Province or state code (optional): the subdivision part only, without the country prefix and not the full ISO 3166-2 code (e.g. \"CA\" for California, \"ON\" for Ontario, \"B\" for Barcelona; never \"US-CA\" or \"ES-B\"). Only the Shopify checkout prefill reads it."
}
},
"description": "Destination address. Required: this tool does not prompt for it.",
"additionalProperties": true
}
},
"additionalProperties": true
}Returns the complete site map of Trusteed: all public pages organized by category. Use this to discover what sections are available (docs, blog, integrations, legal, marketing) and find the right path before calling get_page_content.
| Argument | Type | Description |
|---|---|---|
| category | string | Filter pages by category: commerce, docs, legal, blog, marketing, integrations |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"category": {
"enum": [
"commerce",
"docs",
"legal",
"blog",
"marketing",
"integrations"
],
"type": "string",
"description": "Filter pages by category: commerce, docs, legal, blog, marketing, integrations"
}
},
"additionalProperties": true
}Get Demo Store's signed trust score (v4.1, 0-100) with per-signal data quality, confidence level, and a detached JWS for offline verification. Don't trust the number — verify it: download the JWKS at jwks_snapshot_uri, validate jws_compact with signing_kid, and recompute payload_hash_sha256.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": true
}Retrieve the signed trust receipt for a checkout. A receipt records the complete_checkout call; read `order_placed` before telling anyone a purchase happened. Returns the receipt id, the JWS signature and how to verify it. Issuance is asynchronous: right after complete_checkout this may answer `status: "pending"` with a retry delay. `pending` with code `receipt_pending` means the purchase completed and the receipt is on its way; `checkout_in_progress` means the complete_checkout call is still running. Only the credential that made the purchase can read its receipt. A receipt attests that the call happened, not that money moved: read `settlement` (it is `not_attested` unless the payment rail confirmed it). PREFER THE CART CARD: if the purchase was completed on an interactive card, it already fetches and shows this receipt itself right after the order — calling this tool yourself right after is usually redundant and opens a new card in the transcript. Call it yourself only when there is no interactive card, or the buyer asks for the receipt later in a new turn. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| order_id | string | The order id of a completed purchase, when you have the order but not the checkout session. Provide this or checkout_session_id. |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| checkout_session_id | string | The checkout session id returned by create_cart and echoed by complete_checkout. Provide this or order_id. |
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.
| Argument | Type | Description |
|---|---|---|
| cart_id* | string | Cart session ID returned by create_cart |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| payment_mandate | any | 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. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"cart_id": {
"type": "string",
"description": "Cart session ID returned by create_cart"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"payment_mandate": {
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "string"
}
],
"description": "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."
}
},
"additionalProperties": true
}Read-only price quote. Does not advance the session, open approvals or enable payment. To pay, call preview_checkout. Computes the same totals as preview_checkout for this cart (subtotal, shipping, discount, tax status, total_is_final), with status QUOTE_ONLY, but not the same checks: it does not check your payment mandate's spending cap; preview_checkout does. Read-only on Trusteed's side: where the store prices orders on its own platform (WooCommerce), the store builds a temporary cart to compute the quote and discards it. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| cart_id* | string | Cart session ID returned by create_cart |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"cart_id": {
"type": "string",
"description": "Cart session ID returned by create_cart"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
}
},
"additionalProperties": true
}Full-text search across all Trusteed public documentation: pages, blog posts, FAQ entries, error codes, the agent checkout guide, and the tools of this endpoint. Returns ranked results by relevance. Use this to find answers about protocols, pricing, integration guides, trust scores, and more.
| Argument | Type | Description |
|---|---|---|
| type | string | Filter results by type: page, blog, faq, error (error codes), guide (checkout guide sections) or tool (tools served by this endpoint). Omit to search all types. |
| limit | integer | Maximum number of results (1-20, default 10) |
| query* | string | Search query, e.g. 'trust score threshold', 'shopify integration', 'rate limits' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"type": {
"enum": [
"page",
"blog",
"faq",
"error",
"guide",
"tool"
],
"type": "string",
"description": "Filter results by type: page, blog, faq, error (error codes), guide (checkout guide sections) or tool (tools served by this endpoint). Omit to search all types."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 20,
"minimum": 1,
"description": "Maximum number of results (1-20, default 10)"
},
"query": {
"type": "string",
"maxLength": 200,
"minLength": 2,
"description": "Search query, e.g. 'trust score threshold', 'shopify integration', 'rate limits'"
}
},
"additionalProperties": true
}Search products in Demo Store. Returns matching products with prices, images, availability, and direct links. Results include data for generating a visual product carousel artifact with category filtering.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Number of results (1-50) |
| query | string | Search query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products. |
| cursor | string | Opaque pagination cursor from next_cursor of a previous response. Only valid for the SAME query, category, price range and sort_by — a cursor replayed against different filters is rejected, not silently applied. |
| compact | boolean | When true, the same products are described only once instead of twice. `structuredContent.products` stays the full typed record — every field, every product, untouched — but the text reply becomes a short id/title/price/currency/availability line per product instead of a markdown re-narration of that same data (images, links, ratings inline). Nothing that asserts trust is affected: `merchant_trust`, `rating_provenance` and `sort_provenance_warning` are never trimmed by this flag. Ignored when `field_mask` is also set — a field mask already replaces the narration with a compact listing, so there is nothing left for `compact` to cut. |
| sort_by | string | Sort order for results |
| category | string |
Search products with enriched data including structured attributes, variants, GTIN, and images. Ideal for comparison and detailed product discovery. Matching is keyword/substring-based (title, description, tags, vendor) with rating-then-review ordering — the rating and review count it orders by are asserted by the merchant and are not verified by Trusteed. Use this when you have concrete keywords, a category, or a price range.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max results (1-20) |
| query* | string | Search query |
| category | string | Filter by category |
| max_price | number | Maximum price |
| min_price | number | Minimum price |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 20,
"minimum": 1,
"description": "Max results (1-20)"
},
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Search query"
},
"category": {
"type": "string",
"description": "Filter by category"
},
"max_price": {
"type": "number",
"description": "Maximum price"
},
"min_price": {
"type": "number",
"description": "Minimum price"
}
},
"additionalProperties": true
}Select a shipping method for the cart. Must call get_shipping_rates first and provide idempotency_key. Reuse the same key for retries of the same cart and option; use a new key if either changes. PREFER THE CART CARD: if there is an interactive card for this cart, let the buyer pick shipping there instead of calling this tool yourself — it keeps the flow in one card instead of opening a new one per step. 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.
| Argument | Type | Description |
|---|---|---|
| cart_id* | string | Cart session ID |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| idempotency_key | string | REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
| shipping_handle* | string | Shipping method handle from get_shipping_rates |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"shipping_handle"
],
"properties": {
"cart_id": {
"type": "string",
"description": "Cart session ID"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
},
"shipping_handle": {
"type": "string",
"description": "Shipping method handle from get_shipping_rates"
}
},
"additionalProperties": true
}Cancel a UCP checkout session. Transitions to 'canceled' status. Cannot cancel already completed checkouts. 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. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| reason | string | Optional cancellation reason |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| checkout_id* | string | UCP checkout session ID (valid UUID) |
| idempotency_key | string | REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_id"
],
"properties": {
"reason": {
"type": "string",
"description": "Optional cancellation reason"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"checkout_id": {
"type": "string",
"description": "UCP checkout session ID (valid UUID)"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
}
},
"additionalProperties": true
}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, issued by the platform, not written by you. Call `preview_checkout` for this cart, open the `approval_url` it returns, poll `approval_status_url` with your agent credential, and send the mandate you receive as the `payment_mandate` argument or an `X-Payment-Mandate` header. The approval is bound to your agent credential and the cart; it does not verify that a person was present. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| ap2 | object | AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization. |
| meta | any | 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 | object | Buyer name and email, needed to request the approval link. |
| payment | object | UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token. |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| checkout_id |
Create a UCP (Universal Commerce Protocol) checkout session from line items. Returns a UCP checkout object with status 'incomplete'. Starts the UCP flow (ucp_* tools); for the standard flow use create_cart instead. Do not mix the two flows on the same purchase. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| meta | any | UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters). |
| label | string | Optional label for additional identifiers (e.g. external order ref, multi-PSP reference) |
| intent | object | Intent context for relevance and personalization |
| currency* | string | ISO 4217 currency code (e.g. USD) |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| line_items* | array | Line items for the checkout |
| idempotency_key | string | REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
Retrieve a UCP checkout session by ID. Returns the current state of the checkout. 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. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| meta | any | UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters). |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| checkout_id* | string | UCP checkout session ID (valid UUID) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_id"
],
"properties": {
"meta": {
"description": "UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters)."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"checkout_id": {
"type": "string",
"description": "UCP checkout session ID (valid UUID)"
}
},
"additionalProperties": true
}Preview a UCP checkout and move it to ready-for-payment. Call after destination and shipping are set, before ucp_complete_checkout. Use ONLY for a checkout created with ucp_create_checkout. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| meta | any | UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters). |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| checkout_id* | string | UCP checkout session ID (valid UUID) |
| payment_mandate | any | 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. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_id"
],
"properties": {
"meta": {
"description": "UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters)."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"checkout_id": {
"type": "string",
"description": "UCP checkout session ID (valid UUID)"
},
"payment_mandate": {
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "string"
}
],
"description": "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."
}
},
"additionalProperties": true
}Update a UCP checkout session. Send line_items to replace all lines (each line may name a variant_id), and/or fulfillment to set the delivery address (fulfillment.destination, which returns the shipping options) and choose one (fulfillment.selected_option_id, which adds shipping to the totals). Only allowed when status is 'incomplete'. Use ONLY for sessions created with ucp_create_checkout; for the standard flow use create_cart and select_shipping_option. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| meta | any | UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters). |
| currency | string | ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency. |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| line_items | array | Replacement line items (replaces all lines). Omit to leave the lines as they are. |
| checkout_id* | string | UCP checkout session ID (valid UUID) |
| fulfillment | object | Delivery. Send destination first, then selected_option_id (or both in one call). |
| idempotency_key | string |
Check a trust receipt's signature, revocation and chain coverage from inside this session (v1.0 receipts only; other profiles answer `unsupported_profile`, not invalid). LIMIT: the issuer verifies its own receipt (`verified_by: issuer`, `independent: false`), so this is a consistency check, not proof to a third party; `independent_verification` tells you how to verify it yourself against the public JWKS. Pass the `jws` from get_trust_receipt. Checkout guide: read the MCP resource trusteed://guides/checkout.
| Argument | Type | Description |
|---|---|---|
| jws* | string | The compact JWS of the receipt (the `jws` field returned by get_trust_receipt). |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"jws"
],
"properties": {
"jws": {
"type": "string",
"maxLength": 16384,
"minLength": 1,
"description": "The compact JWS of the receipt (the `jws` field returned by get_trust_receipt)."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
}
},
"additionalProperties": true
}| Argument |
|---|
| Type |
|---|
| Description |
|---|
| buyer | object | Optional buyer contact information |
| agent_key | string | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. |
| cel_context | object | Optional. Send only evidence you can substantiate; it can only make a check stricter, never looser. Unknown keys or out-of-range values are rejected with INVALID_ARGUMENT. Keys: key_age_hours, requested_scopes, product_categories, price_delta_bps, discount_codes_tried, discount_bps, lowest_stock, return_policy_mismatch, is_subscription, autorenew_consent, is_b2b, purchase_order_hash, shipping_po_box, shipping_freight_forwarder, provider_confidence, stored_value_cents, cross_merchant_abuse, refund_ratio, dispute_count, completed_orders_24h, merchant_orders_1h, digital_good_types, agent_provider_id. |
| kyapay_token | string | Not available for payment: charging with KYApay is switched off, because KYApay is identity verification here, not a payment rail. A call that passes this token is rejected with PAYMENT_METHOD_NOT_CONFIGURED before anything is charged or written. The Skyfire KYA token is used for identity on the REST API, not in this tool. |
| payment_method | string | Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY is not available for payment: KYApay is identity verification here, so a request with KYAPAY is rejected without charging anything. ACP (Stripe-native settlement) returns a 'not enabled' response unless this deployment enables native settlement; when enabled it charges the Stripe Shared Payment Token passed as shared_payment_token. X402 is available through the configured x402 protocol flow, not this checkout tool. MOCK moves no money: it completes the order without charging. Whether a store accepts it depends on the store's configuration (it is the default on demo-store). Defaults to MOCK if not specified. |
| payment_option | string | 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* | string | 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_mandate | any | 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. |
| checkout_session_id* | string | Checkout session ID from preview_checkout — the same value as create_cart's cart_id (must be a valid UUID) |
| save_payment_method | boolean | Only with PayPal at a store that charges into its own PayPal account, for a signed-in buyer (not guest access), and only when the person asked for it: true asks PayPal to save this PayPal account during this purchase, so later purchases at this store can be charged without a new approval, within per-charge and daily limits. Never set it on your own initiative. In any other case it is ignored and the response says so in details; it never causes an error. |
| shared_payment_token | string | 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. |
| reconfirmed_state_hash | string | SHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_session_id",
"idempotency_key"
],
"properties": {
"buyer": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Buyer first name and surname(s) as one string, e.g. \"Ana García López\". Prefilled in the store checkout."
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer email address (e.g. [email protected]). Prefilled in the store checkout."
},
"phone": {
"type": "string",
"description": "Buyer phone number"
}
},
"description": "Optional buyer contact information",
"additionalProperties": true
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"cel_context": {
"type": "object",
"description": "Optional. Send only evidence you can substantiate; it can only make a check stricter, never looser. Unknown keys or out-of-range values are rejected with INVALID_ARGUMENT. Keys: key_age_hours, requested_scopes, product_categories, price_delta_bps, discount_codes_tried, discount_bps, lowest_stock, return_policy_mismatch, is_subscription, autorenew_consent, is_b2b, purchase_order_hash, shipping_po_box, shipping_freight_forwarder, provider_confidence, stored_value_cents, cross_merchant_abuse, refund_ratio, dispute_count, completed_orders_24h, merchant_orders_1h, digital_good_types, agent_provider_id.",
"additionalProperties": {}
},
"kyapay_token": {
"type": "string",
"description": "Not available for payment: charging with KYApay is switched off, because KYApay is identity verification here, not a payment rail. A call that passes this token is rejected with PAYMENT_METHOD_NOT_CONFIGURED before anything is charged or written. The Skyfire KYA token is used for identity on the REST API, not in this tool."
},
"payment_method": {
"enum": [
"ACP",
"KYAPAY",
"PAYPAL",
"MOCK",
"X402"
],
"type": "string",
"description": "Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY is not available for payment: KYApay is identity verification here, so a request with KYAPAY is rejected without charging anything. ACP (Stripe-native settlement) returns a 'not enabled' response unless this deployment enables native settlement; when enabled it charges the Stripe Shared Payment Token passed as shared_payment_token. X402 is available through the configured x402 protocol flow, not this checkout tool. MOCK moves no money: it completes the order without charging. Whether a store accepts it depends on the store's configuration (it is the default on demo-store). Defaults to MOCK if not specified."
},
"payment_option": {
"enum": [
"demo_card",
"demo_wallet",
"own_wallet",
"merchant_card",
"paypal"
],
"type": "string",
"description": "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": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "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_mandate": {
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "string"
}
],
"description": "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."
},
"checkout_session_id": {
"type": "string",
"description": "Checkout session ID from preview_checkout — the same value as create_cart's cart_id (must be a valid UUID)"
},
"save_payment_method": {
"type": "boolean",
"description": "Only with PayPal at a store that charges into its own PayPal account, for a signed-in buyer (not guest access), and only when the person asked for it: true asks PayPal to save this PayPal account during this purchase, so later purchases at this store can be charged without a new approval, within per-charge and daily limits. Never set it on your own initiative. In any other case it is ignored and the response says so in details; it never causes an error."
},
"shared_payment_token": {
"type": "string",
"pattern": "^spt_[A-Za-z0-9_]+$",
"description": "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."
},
"reconfirmed_state_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "SHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew."
}
},
"additionalProperties": true
}| idempotency_key |
| string |
| REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
| agent_session_id | string | Opaque agent session identifier for cart resume across sessions |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"product_id"
],
"properties": {
"quantity": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Quantity"
},
"product_id": {
"type": "string",
"description": "Product ID"
},
"variant_id": {
"type": "string",
"description": "Variant ID (optional). Must match a variant id listed by get_product_details; an unknown id is rejected rather than silently replaced by the default variant."
}
},
"additionalProperties": false
},
"minItems": 1,
"description": "Items to add to cart"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"agent_token": {
"type": "string",
"description": "JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. A malformed token fails with AGENT_TOKEN_INVALID on any platform. On Shopify stores Trusteed also verifies the signature on receipt against a registered key that must belong to the calling agent (otherwise AGENT_TOKEN_INVALID and no cart is created), and the checkout Function verifies it again offline at payment. On other platforms Trusteed checks its structure only and forwards it to the store."
},
"display_context": {
"enum": [
"webview",
"headless"
],
"type": "string",
"default": "headless",
"description": "Agent display capability: webview (browser) or headless"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
},
"agent_session_id": {
"type": "string",
"description": "Opaque agent session identifier for cart resume across sessions"
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"order_id": {
"type": "string",
"description": "The order id of a completed purchase, when you have the order but not the checkout session. Provide this or checkout_session_id."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"checkout_session_id": {
"type": "string",
"description": "The checkout session id returned by create_cart and echoed by complete_checkout. Provide this or order_id."
}
},
"additionalProperties": true
}| Filter by category slug |
| max_price | number | Maximum price filter |
| min_price | number | Minimum price filter |
| field_mask | array | Return only these product fields, to spend less of your context on a large catalogue. `id` is always included. Supplying a mask also drops the carousel/UI payloads, which are the bulk of a full response. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 50,
"minimum": 1,
"description": "Number of results (1-50)"
},
"query": {
"type": "string",
"maxLength": 200,
"description": "Search query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products."
},
"cursor": {
"type": "string",
"description": "Opaque pagination cursor from next_cursor of a previous response. Only valid for the SAME query, category, price range and sort_by — a cursor replayed against different filters is rejected, not silently applied."
},
"compact": {
"type": "boolean",
"default": false,
"description": "When true, the same products are described only once instead of twice. `structuredContent.products` stays the full typed record — every field, every product, untouched — but the text reply becomes a short id/title/price/currency/availability line per product instead of a markdown re-narration of that same data (images, links, ratings inline). Nothing that asserts trust is affected: `merchant_trust`, `rating_provenance` and `sort_provenance_warning` are never trimmed by this flag. Ignored when `field_mask` is also set — a field mask already replaces the narration with a compact listing, so there is nothing left for `compact` to cut."
},
"sort_by": {
"enum": [
"relevance",
"price_asc",
"price_desc",
"newest",
"rating"
],
"type": "string",
"default": "relevance",
"description": "Sort order for results"
},
"category": {
"type": "string",
"maxLength": 200,
"description": "Filter by category slug"
},
"max_price": {
"type": "number",
"description": "Maximum price filter",
"exclusiveMinimum": 0
},
"min_price": {
"type": "number",
"description": "Minimum price filter",
"exclusiveMinimum": 0
},
"field_mask": {
"type": "array",
"items": {
"enum": [
"title",
"price",
"compareAtPrice",
"currency",
"image",
"url",
"stockStatus",
"rating",
"reviewCount",
"rating_provenance",
"vendor",
"variants"
],
"type": "string"
},
"description": "Return only these product fields, to spend less of your context on a large catalogue. `id` is always included. Supplying a mask also drops the carousel/UI payloads, which are the bulk of a full response."
}
},
"additionalProperties": true
}| string |
| UCP checkout session ID (valid UUID) |
| x402_payload | any | x402: signed payment for the server offer (omit to get it). |
| payment_option | string | 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* | string | 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 | string | Payment handler the store profile publishes. Omit for default. |
| payment_mandate | any | 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. |
| shared_payment_token | string | 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. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_id",
"idempotency_key"
],
"properties": {
"ap2": {
"type": "object",
"required": [
"checkout_mandate"
],
"properties": {
"checkout_mandate": {
"type": "string",
"pattern": "^[A-Za-z0-9_.~-]+$",
"maxLength": 262144,
"minLength": 1,
"description": "AP2 Checkout Mandate (SD-JWT chain) the user signed over the exact checkout returned by the last ucp_get_checkout."
}
},
"description": "AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization.",
"additionalProperties": true
},
"meta": {
"description": "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": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Buyer full name"
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer email address"
},
"phone": {
"type": "string",
"description": "Buyer phone number"
}
},
"description": "Buyer name and email, needed to request the approval link.",
"additionalProperties": true
},
"payment": {
"type": "object",
"properties": {
"instruments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"credential": {
"type": "object",
"properties": {
"token": {
"type": "string",
"maxLength": 262144,
"description": "AP2 Payment Mandate (SD-JWT chain)."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"maxItems": 16
}
},
"description": "UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token.",
"additionalProperties": true
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"checkout_id": {
"type": "string",
"description": "UCP checkout session ID (valid UUID)"
},
"x402_payload": {
"description": "x402: signed payment for the server offer (omit to get it)."
},
"payment_option": {
"enum": [
"demo_card",
"demo_wallet",
"own_wallet",
"merchant_card",
"paypal"
],
"type": "string",
"description": "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": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "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": {
"enum": [
"stripe",
"x402"
],
"type": "string",
"description": "Payment handler the store profile publishes. Omit for default."
},
"payment_mandate": {
"anyOf": [
{
"type": "object",
"additionalProperties": {}
},
{
"type": "string"
}
],
"description": "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."
},
"shared_payment_token": {
"type": "string",
"pattern": "^spt_[A-Za-z0-9_]+$",
"description": "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."
}
},
"additionalProperties": true
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"currency",
"line_items"
],
"properties": {
"meta": {
"description": "UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters)."
},
"label": {
"type": "string",
"description": "Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)"
},
"intent": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"description": "Intent action (e.g. 'purchase', 'gift', 'compare')"
},
"locale": {
"type": "string",
"description": "ISO locale"
},
"context": {
"type": "string",
"description": "Natural language context for personalization"
}
},
"description": "Intent context for relevance and personalization",
"additionalProperties": true
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO 4217 currency code (e.g. USD)"
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"product_id",
"title",
"quantity",
"price"
],
"properties": {
"price": {
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "number",
"minimum": 0,
"description": "Ignored: the catalogue price is used and returned per line. Any non-negative integer is accepted."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO 4217 currency code"
}
},
"additionalProperties": false
},
"title": {
"type": "string",
"minLength": 1,
"description": "Ignored: the catalogue title is used. Any non-empty string is accepted."
},
"quantity": {
"type": "integer",
"description": "Quantity",
"exclusiveMinimum": 0
},
"product_id": {
"type": "string",
"minLength": 1,
"description": "Product identifier"
},
"variant_id": {
"type": "string",
"minLength": 1,
"description": "Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply."
}
},
"additionalProperties": true
},
"minItems": 1,
"description": "Line items for the checkout"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
}
},
"additionalProperties": true
}| REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkout_id"
],
"properties": {
"meta": {
"description": "UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters)."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency."
},
"agent_key": {
"type": "string",
"description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"product_id",
"title",
"quantity",
"price"
],
"properties": {
"price": {
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "number",
"minimum": 0,
"description": "Ignored: the catalogue price is used and returned per line. Any non-negative integer is accepted."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO 4217 currency code"
}
},
"additionalProperties": false
},
"title": {
"type": "string",
"minLength": 1,
"description": "Ignored: the catalogue title is used. Any non-empty string is accepted."
},
"quantity": {
"type": "integer",
"description": "Quantity",
"exclusiveMinimum": 0
},
"product_id": {
"type": "string",
"minLength": 1,
"description": "Product identifier"
},
"variant_id": {
"type": "string",
"minLength": 1,
"description": "Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply."
}
},
"additionalProperties": true
},
"minItems": 1,
"description": "Replacement line items (replaces all lines). Omit to leave the lines as they are."
},
"checkout_id": {
"type": "string",
"description": "UCP checkout session ID (valid UUID)"
},
"fulfillment": {
"type": "object",
"properties": {
"destination": {
"type": "object",
"required": [
"address1",
"city",
"country_code",
"zip"
],
"properties": {
"zip": {
"type": "string",
"description": "Postal / ZIP code"
},
"city": {
"type": "string",
"description": "City"
},
"address1": {
"type": "string",
"description": "Street address"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code (e.g. US, ES)"
},
"province_code": {
"type": "string",
"description": "Province or state code (optional)"
}
},
"description": "Delivery address. Sending it loads the shipping options for that destination; the response lists them in fulfillment.options.",
"additionalProperties": true
},
"selected_option_id": {
"type": "string",
"description": "Id of one of fulfillment.options. Choosing it adds the shipping amount to the totals."
}
},
"description": "Delivery. Send destination first, then selected_option_id (or both in one call).",
"additionalProperties": true
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:/-]{1,128}$",
"maxLength": 128,
"description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
}
},
"additionalProperties": true
}