UCP Gateway

shopping checkout update

shopping_checkout_update

Update checkout with a typed buyer (recommended for address/phone corrections) and/or a full checkout object. Buyer phone should be E.164 and country must be ISO-2.

Input Schema

TableJSON Schema

Name	Required	Description
`buyer`	No	Buyer-provided checkout contact and shipping details. Never invent PII; omit phone if unavailable.
`agent_id`	Yes	Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool.
`checkout`	No	Optional full checkout replacement payload accepted by the provider. Prefer typed buyer for address/phone corrections; buyer address fields placed here are canonicalized into buyer/context/fulfillment with phone_number. Never include payment credentials.
`checkout_id`	Yes	Provider checkout ID returned by checkout tools.
`merchant_domain`	Yes	Merchant host such as 'outboundpower.com' or 'example.myshopify.com'. Do not include a URL scheme, localhost, private IP, file URL, or ftp URL.
`client_action_id`	No	Optional UUID generated once for an explicit buyer/operator-confirmed cart or checkout mutation. Reuse only when retrying the same confirmed action.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	True for successful tool execution; false for structured tool errors.
`raw`	No	Redacted raw provider or registry payload for debugging. Shape may vary by upstream endpoint.
`error`	No	Structured tool error.
`message`	Yes	Human-readable result summary or recovery message.
`checkout`	No	Safe provider checkout summary including id, status, continue_url, totals, line_items, and messages when provided.
`warnings`	No	Non-fatal checkout or handoff warnings.
`next_step`	Yes	Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions.
`merchant_domain`	No	Resolved merchant domain.
`partial_success`	No	True when Shopify flagged the upstream result as an error but returned a usable checkout payload (id plus continue_url or recognized status). The gateway result is still actionable; this is not an order confirmation.
`upstream_is_error`	No	True when the upstream Shopify MCP response set isError/ok:false while still returning a usable checkout payload. Present for debugging; does not make the gateway tool result an error.
`commerce_session_id`	No	Internal gateway commerce session UUID when one was created.
`requires_escalation`	No	True when Shopify requires the buyer to finish a step on the merchant-hosted checkout page (status requires_escalation/requires_buyer_input or escalation warnings). The continue_url is still actionable.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedJun 26, 2026

changedInput schema / description

Previous value: -"Arguments for updating a checkout."New value: +"Arguments for updating a checkout. Provide checkout and/or buyer."

addedInput schema / properties / buyer

Added value: +{
+  "additionalProperties": false,
+  "description": "Buyer-provided checkout contact and shipping details. Never invent PII; omit phone if unavailable.",
+  "properties": {
+    "address_country": {
+      "description": "ISO 3166-1 alpha-2 country code. Use 'US', not 'USA'.",
+      "type": "string"
+    },
+    "address_locality": {
+      "description": "Buyer-provided shipping city/locality.",
+      "type": "string"
+    },
+    "address_region": {
+      "description": "Buyer-provided shipping state/province/region.",
+      "type": "string"
+    },
+    "email": {
+      "description": "Buyer email for merchant checkout contact and order confirmation.",
+      "type": "string"
+    },
+    "first_name": {
+      "description": "Buyer-provided shipping first name.",
+      "type": "string"
+    },
+    "last_name": {
+      "description": "Buyer-provided shipping last name.",
+      "type": "string"
+    },
+    "phone": {
+      "description": "Buyer phone. Prefer E.164, e.g. +15555550100. Non-E.164 values are accepted but may be dropped before reaching the provider and will surface a non-fatal warning.",
+      "type": "string"
+    },
+    "phone_number": {
+      "description": "Canonical buyer phone alias. Prefer E.164. Equivalent to `phone`; if both are set, phone_number wins.",
+      "type": "string"
+    },
+    "postal_code": {
+      "description": "Buyer-provided shipping postal code.",
+      "type": "string"
+    },
+    "street_address": {
+      "description": "Buyer-provided shipping street address.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "email",
+    "first_name",
+    "last_name",
+    "street_address",
+    "address_locality",
+    "address_region",
+    "postal_code",
+    "address_country"
+  ],
+  "type": "object"
+}

changedInput schema / properties / checkout / description

Previous value: -"Full checkout replacement payload accepted by the provider. Use sparingly; prefer E.164 phone and ISO-2 destination country; never include payment credentials."New value: +"Optional full checkout replacement payload accepted by the provider. Prefer typed buyer for address/phone corrections; buyer address fields placed here are canonicalized into buyer/context/fulfillment with phone_number. Never include payment credentials."

changedInput schema / required

Previous value: -[
-  "agent_id",
-  "merchant_domain",
-  "checkout_id",
-  "checkout"
-]New value: +[
+  "agent_id",
+  "merchant_domain",
+  "checkout_id"
+]

addedOutput schema / properties / partial_success

Added value: +{
+  "description": "True when Shopify flagged the upstream result as an error but returned a usable checkout payload (id plus continue_url or recognized status). The gateway result is still actionable; this is not an order confirmation.",
+  "type": "boolean"
+}

addedOutput schema / properties / requires_escalation

Added value: +{
+  "description": "True when Shopify requires the buyer to finish a step on the merchant-hosted checkout page (status requires_escalation/requires_buyer_input or escalation warnings). The continue_url is still actionable.",
+  "type": "boolean"
+}

addedOutput schema / properties / upstream_is_error

Added value: +{
+  "description": "True when the upstream Shopify MCP response set isError/ok:false while still returning a usable checkout payload. Present for debugging; does not make the gateway tool result an error.",
+  "type": "boolean"
+}

First observedJun 5, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations indicate mutation (readOnlyHint=false) and non-destructiveness. The description adds behavioral details: phone format acceptance and warnings, canonicalization of buyer fields, and prohibition of payment credentials. No contradiction.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the main action, followed by crucial format notes. No superfluous words; every sentence adds value.

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

Completeness4/5

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

Given the complexity (nested objects, many parameters, output schema exists), the description covers the main usage pattern and format constraints. It could mention that it updates an existing checkout, but that is implicit from name and context.

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%, but the description adds value by explaining the purpose of buyer vs checkout parameters, recommending preference, and specifying constraints like phone_number alias behavior and payment credential exclusion.

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 clearly states 'Update checkout with a typed buyer and/or a full checkout object,' specifying the action and resources. It distinguishes from create/get by the verb 'update' and the mention of corrections, aligning with sibling tool names.

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

Usage Guidelines4/5

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

It recommends using typed buyer for address/phone corrections and provides format constraints (E.164, ISO-2). It does not explicitly state when not to use, but the context is clear. Sibling differentiation is implicit via the action.

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

All UCP Gateway tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?