Tool tree
Shop’s developer playground for product discovery, carts and agent commerce.
Implementation
gradeNot graded
gradeNot graded
shop_skillAnswer
Read this skill before using the Shop commerce tools. Start with {} for the entrypoint and follow exact linked references when relevant. Reads are quiet and do not change the terminal.
View tool JSON
{
"name": "shop_skill",
"kind": "answer",
"impl": "imperative",
"description": "Read this skill before using the Shop commerce tools. Start with {} for the entrypoint and follow exact linked references when relevant. Reads are quiet and do not change the terminal.",
"inputSchema": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"enum": [
"references/catalog.md",
"references/transactions.md"
],
"description": "One exact linked skill reference. Omit to read the entrypoint."
}
},
"additionalProperties": false
}
}shop_sign_inAction
Connect Shop only when the user agrees. Start with wait:0 to return the current public activation URL and user code without polling. After the user approves in another tab, call wait:90. Only data.signed_in:true confirms sign-in. This never performs a purchase.
View tool JSON
{
"name": "shop_sign_in",
"kind": "act",
"impl": "imperative",
"description": "Connect Shop only when the user agrees. Start with wait:0 to return the current public activation URL and user code without polling. After the user approves in another tab, call wait:90. Only data.signed_in:true confirms sign-in. This never performs a purchase.",
"inputSchema": {
"type": "object",
"properties": {
"wait": {
"type": "integer",
"enum": [
0,
90
],
"default": 0,
"description": "Use 0 to obtain the URL/code. Use 90 only after the user approves."
}
},
"additionalProperties": false
}
}clear_terminalAction
Clear idle pending input, the terminal display and scrollback. Refuses while a command is active. Does not sign out.
View tool JSON
{
"name": "clear_terminal",
"kind": "act",
"impl": "imperative",
"description": "Clear idle pending input, the terminal display and scrollback. Refuses while a command is active. Does not sign out.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
}search_catalogAnswer
Find by query/like. Anonymous works; sign-in adds saved preferences. Context soft; filters hard. Matches/options do not prove the variant. Check messages; ground options, availability, price/currency, rating, seller, and URL in the exact offer. Use get_product only for unresolved facts/options. Amounts are minor units.
View tool JSON
{
"name": "search_catalog",
"kind": "answer",
"impl": "imperative",
"description": "Find by query/like. Anonymous works; sign-in adds saved preferences. Context soft; filters hard. Matches/options do not prove the variant. Check messages; ground options, availability, price/currency, rating, seller, and URL in the exact offer. Use get_product only for unresolved facts/options. Amounts are minor units.",
"inputSchema": {
"$defs": {
"d0": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d1": {
"additionalProperties": true,
"properties": {
"categories": {
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"description": "Inclusive context.currency minor-unit bounds.",
"properties": {
"max": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
]
},
"min": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
]
}
},
"title": "Price Filter",
"type": "object"
}
},
"title": "Search Filters",
"type": "object"
},
"d2": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"properties": {
"catalog": {
"allOf": [
{
"allOf": [
{
"properties": {
"context": {
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d0"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"filters": {
"$ref": "#/$defs/d1"
},
"pagination": {
"properties": {
"cursor": {
"type": "string"
},
"limit": {
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"query": {
"type": "string"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
]
},
"title": "Signals",
"type": "object"
}
},
"type": "object"
},
{
"anyOf": [
{
"required": [
"query"
]
},
{
"required": [
"like"
]
}
],
"properties": {
"filters": {
"allOf": [
{
"$ref": "#/$defs/d1"
},
{
"allOf": [
{
"properties": {
"available": {
"default": true,
"type": "boolean"
}
},
"title": "Shopify Filters",
"type": "object"
},
{
"properties": {
"condition": {
"items": {
"type": "string"
},
"type": "array"
},
"ships_from": {
"items": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
}
],
"title": "Global Filters"
},
{
"properties": {
"attributes": {
"items": {
"properties": {
"name": {
"type": "string"
},
"values": {
"items": {
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"name",
"values"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"categories": {
"items": {
"type": "string"
},
"type": "array"
},
"price_tier": {
"items": {
"type": "string"
},
"type": "array"
},
"rating": {
"properties": {
"variant": {
"properties": {
"min": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"min_count": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
],
"title": "Global Search Filters"
}
},
"type": "object"
}
],
"title": "Global Search Request",
"type": "object"
},
{
"anyOf": [
{
"required": [
"query"
]
},
{
"required": [
"like"
]
}
],
"properties": {
"catalog_id": {
"description": "Saved catalog ID whose configuration constrains search.",
"type": "string"
},
"context": {
"additionalProperties": true,
"properties": {
"address_country": {
"type": "string"
},
"address_region": {
"type": "string"
},
"currency": {
"type": "string"
},
"intent": {
"type": "string"
},
"language": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"type": "object"
},
"filters": {
"additionalProperties": true,
"description": "Hard requirements; fields AND, stated lists OR. Check messages/every offer.",
"properties": {
"attributes": {
"description": "Attributes AND; each value list OR. Check ignored-name messages.",
"items": {
"properties": {
"name": {
"description": "Supported names: Color, Size, Target gender.",
"type": "string"
},
"values": {
"description": "OR across taxonomy values.",
"items": {
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"name",
"values"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"available": {
"default": true,
"description": "true/omitted: sale-ready only; false: include unavailable.",
"type": "boolean"
},
"categories": {
"description": "OR taxonomy category GIDs.",
"items": {
"type": "string"
},
"type": "array"
},
"condition": {
"description": "OR new/secondhand; omit for either.",
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"properties": {
"max": {
"type": "integer"
},
"min": {
"type": "integer"
}
},
"type": "object"
},
"price_tier": {
"description": "OR category-relative tiers, not a budget cap; check ignored-value messages.",
"items": {
"type": "string"
},
"type": "array"
},
"rating": {
"properties": {
"variant": {
"description": "At least one variant must meet these thresholds.",
"properties": {
"min": {
"description": "Minimum rating on a 0–5 scale.",
"maximum": 5,
"minimum": 0,
"type": "number"
},
"min_count": {
"description": "Minimum variant review count.",
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
},
"ships_from": {
"description": "OR origins; omit for any.",
"items": {
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"description": "Hard destination; context may supply it if omitted; matching context may refine estimates.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"description": "OR seller.id Shop GIDs/domains; check unmatched messages.",
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
},
"like": {
"description": "One product/variant ID or image reference for similarity. Add query to refine an image reference. Put hard requirements in supported filters.",
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"id": {
"description": "Exact Shopify product or variant GID.",
"pattern": "^gid://shopify/",
"type": "string"
}
},
"required": [
"id"
],
"title": "Item Reference"
},
{
"additionalProperties": false,
"properties": {
"image": {
"additionalProperties": false,
"properties": {
"content_type": {
"description": "Image MIME type, e.g. image/jpeg or image/webp.",
"type": "string"
},
"data": {
"contentEncoding": "base64",
"description": "Base64-encoded image bytes.",
"type": "string"
}
},
"required": [
"content_type",
"data"
],
"type": "object"
}
},
"required": [
"image"
],
"title": "Image Content"
}
],
"title": "Like Item",
"type": "object"
},
"maxItems": 2,
"minItems": 1,
"type": "array"
},
"pagination": {
"properties": {
"cursor": {
"description": "Pass unchanged with the same query, like, context, and filters.",
"type": "string"
},
"limit": {
"default": 10,
"description": "Page size. Defaults to 10; maximum 50.",
"maximum": 50,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"query": {
"description": "Preserve intent; clarify only. Add no preferences/popularity. Put hard requirements in supported filters.",
"type": "string"
},
"signals": {
"additionalProperties": true,
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
{
"not": {
"required": [
"attribution"
]
}
},
{
"not": {
"required": [
"view"
]
}
}
],
"type": "object"
}
},
"required": [
"catalog"
],
"type": "object"
}
}lookup_catalogAnswer
Resolve known product/variant IDs, GTINs, UPCs, or URLs. Use search_catalog for discovery; get_product only for unresolved options/details. Preserve IDs/URLs; ground claims in the exact offer. Amounts are minor units.
View tool JSON
{
"name": "lookup_catalog",
"kind": "answer",
"impl": "imperative",
"description": "Resolve known product/variant IDs, GTINs, UPCs, or URLs. Use search_catalog for discovery; get_product only for unresolved options/details. Preserve IDs/URLs; ground claims in the exact offer. Amounts are minor units.",
"inputSchema": {
"$defs": {
"d0": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d1": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"properties": {
"catalog": {
"allOf": [
{
"allOf": [
{
"properties": {
"context": {
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d0"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"filters": {
"allOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"description": "Inclusive context.currency minor-unit bounds.",
"properties": {
"max": {
"allOf": [
{
"$ref": "#/$defs/d1"
}
]
},
"min": {
"allOf": [
{
"$ref": "#/$defs/d1"
}
]
}
},
"title": "Price Filter",
"type": "object"
}
},
"title": "Search Filters",
"type": "object"
}
]
},
"ids": {
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"ids"
],
"type": "object"
},
{
"properties": {
"filters": {
"allOf": [
{
"properties": {
"available": {
"default": true,
"type": "boolean"
}
},
"title": "Shopify Filters",
"type": "object"
},
{
"properties": {
"condition": {
"items": {
"type": "string"
},
"type": "array"
},
"ships_from": {
"items": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
}
],
"title": "Global Filters"
}
},
"type": "object"
}
],
"title": "Global Lookup Request",
"type": "object"
},
{
"properties": {
"context": {
"additionalProperties": true,
"properties": {
"address_country": {
"type": "string"
},
"address_region": {
"type": "string"
},
"currency": {
"type": "string"
},
"intent": {
"type": "string"
},
"language": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"type": "object"
},
"filters": {
"additionalProperties": true,
"description": "Hard requirements; fields AND, stated lists OR. Verify the offer.",
"properties": {
"available": {
"default": true,
"description": "true/omitted: sale-ready only; false: include unavailable.",
"type": "boolean"
},
"categories": {
"description": "OR taxonomy category GIDs.",
"items": {
"type": "string"
},
"type": "array"
},
"condition": {
"description": "OR new/secondhand; omit for either.",
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"properties": {
"max": {
"type": "integer"
},
"min": {
"type": "integer"
}
},
"type": "object"
},
"ships_from": {
"description": "OR origins; omit for any.",
"items": {
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"description": "Hard destination; context may supply it if omitted; matching context may refine estimates.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"description": "OR seller.id Shop GIDs/domains; check unmatched messages.",
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
},
"ids": {
"description": "Up to 50 exact IDs/URLs; preserve returned values.",
"items": {
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
},
"signals": {
"additionalProperties": true,
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"type": "object"
}
},
"required": [
"ids"
],
"type": "object"
},
{
"not": {
"required": [
"attribution"
]
}
},
{
"not": {
"required": [
"view"
]
}
}
],
"type": "object"
}
},
"required": [
"catalog"
],
"type": "object"
}
}get_productAnswer
Resolve missing details/options for a known product. Use its returned ID/exact option name-label pairs; verify effective selection because requests may drop. Ground availability, seller, price/currency, rating, and URL in the exact offer. Skip if prior results prove facts. Amounts are minor units.
View tool JSON
{
"name": "get_product",
"kind": "answer",
"impl": "imperative",
"description": "Resolve missing details/options for a known product. Use its returned ID/exact option name-label pairs; verify effective selection because requests may drop. Ground availability, seller, price/currency, rating, and URL in the exact offer. Skip if prior results prove facts. Amounts are minor units.",
"inputSchema": {
"$defs": {
"d0": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d1": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"properties": {
"catalog": {
"allOf": [
{
"allOf": [
{
"properties": {
"context": {
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d0"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"filters": {
"allOf": [
{
"additionalProperties": true,
"properties": {
"categories": {
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"description": "Inclusive context.currency minor-unit bounds.",
"properties": {
"max": {
"allOf": [
{
"$ref": "#/$defs/d1"
}
]
},
"min": {
"allOf": [
{
"$ref": "#/$defs/d1"
}
]
}
},
"title": "Price Filter",
"type": "object"
}
},
"title": "Search Filters",
"type": "object"
}
]
},
"id": {
"type": "string"
},
"preferences": {
"description": "Ordered option names, relaxed from the end; not hard requirements.",
"items": {
"type": "string"
},
"type": "array"
},
"selected": {
"items": {
"properties": {
"id": {
"description": "Copy returned option_value.id unchanged.",
"type": "string"
},
"label": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"label"
],
"title": "Selected Option",
"type": "object"
},
"type": "array"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"id"
],
"type": "object"
},
{
"properties": {
"filters": {
"allOf": [
{
"properties": {
"available": {
"default": true,
"type": "boolean"
}
},
"title": "Shopify Filters",
"type": "object"
},
{
"properties": {
"condition": {
"items": {
"type": "string"
},
"type": "array"
},
"ships_from": {
"items": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"properties": {
"country": {
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
}
],
"title": "Global Filters"
}
},
"type": "object"
}
],
"title": "Global Get Product Request",
"type": "object"
},
{
"properties": {
"context": {
"additionalProperties": true,
"properties": {
"address_country": {
"type": "string"
},
"address_region": {
"type": "string"
},
"currency": {
"type": "string"
},
"intent": {
"type": "string"
},
"language": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"type": "object"
},
"filters": {
"additionalProperties": true,
"description": "Hard requirements; fields AND, stated lists OR. Verify the offer.",
"properties": {
"available": {
"default": true,
"description": "true/omitted: sale-ready only; false: include unavailable.",
"type": "boolean"
},
"categories": {
"description": "OR taxonomy category GIDs.",
"items": {
"type": "string"
},
"type": "array"
},
"condition": {
"description": "OR new/secondhand; omit for either.",
"items": {
"type": "string"
},
"type": "array"
},
"price": {
"properties": {
"max": {
"type": "integer"
},
"min": {
"type": "integer"
}
},
"type": "object"
},
"ships_from": {
"description": "OR origins; omit for any.",
"items": {
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"type": "array"
},
"ships_to": {
"description": "Hard destination; context may supply it if omitted; matching context may refine estimates.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2.",
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"postal_code": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"country"
],
"type": "object"
},
"shops": {
"description": "OR seller.id Shop GIDs/domains; check unmatched messages.",
"items": {
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"type": "object"
},
"id": {
"description": "Exact returned product ID; resolve URL/variant via lookup_catalog first.",
"type": "string"
},
"preferences": {
"items": {
"type": "string"
},
"type": "array"
},
"selected": {
"description": "Exact returned name/label pairs; verify effective selection because requests may drop.",
"items": {
"properties": {
"label": {
"type": "string"
},
"name": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"signals": {
"additionalProperties": true,
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"type": "object"
}
},
"required": [
"id"
],
"type": "object"
},
{
"not": {
"required": [
"attribution"
]
}
},
{
"not": {
"required": [
"view"
]
}
}
],
"type": "object"
}
},
"required": [
"catalog"
],
"type": "object"
}
}search_locationsAnswer
Search shop's physical stores by city, neighborhood, street or postal code (query), by radius around coordinates the user gave (distance), or by item availability (filters.items); filters combine. One shop per call. Omit filters to list every store.
View tool JSON
{
"name": "search_locations",
"kind": "answer",
"impl": "imperative",
"description": "Search shop's physical stores by city, neighborhood, street or postal code (query), by radius around coordinates the user gave (distance), or by item availability (filters.items); filters combine. One shop per call. Omit filters to list every store.",
"inputSchema": {
"$defs": {
"d0": {
"properties": {
"context": {
"additionalProperties": true,
"allOf": [
{
"$ref": "#/$defs/d1"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d2"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"distance": {
"allOf": [
{
"additionalProperties": true,
"description": "Stores within max meters of an explicit center. Use coordinates the user or host gave; never derive them. The radius is never widened or clamped.",
"properties": {
"center": {
"allOf": [
{
"$ref": "#/$defs/d3"
}
]
},
"max": {
"description": "Inclusive radius in meters.",
"minimum": 0,
"type": "number"
}
},
"required": [
"center",
"max"
],
"title": "Location Distance",
"type": "object"
}
]
},
"filters": {
"additionalProperties": true,
"description": "Hard requirements; fields AND. A merchant rejects a filter it cannot evaluate with invalid_input rather than ignoring it; Shopify stores evaluate items only.",
"properties": {
"amenities": {
"description": "Exact amenity IDs, all required.",
"items": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
],
"examples": [
"dev.ucp.amenity.wi_fi",
"dev.ucp.amenity.parking",
"dev.ucp.amenity.shopping.in_store_pickup",
"dev.ucp.amenity.shopping.curbside_pickup"
],
"title": "Amenity Type"
},
"type": "array"
},
"hours": {
"properties": {
"open_at": {
"description": "RFC 3339 instant the store must be open at.",
"format": "date-time",
"pattern": "(?:[Zz]|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$",
"type": "string"
}
},
"required": [
"open_at"
],
"type": "object"
},
"items": {
"description": "Variant IDs from catalog results; returns stores that have all of them available, up to 10 items per call.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
},
"title": "Location Filter",
"type": "object"
},
"pagination": {
"properties": {
"cursor": {
"type": "string"
},
"limit": {
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"query": {
"description": "City, neighborhood, street or postal code, matched literally (New York, not NY). Omit to list every store.",
"type": "string"
},
"serves": {
"allOf": [
{
"additionalProperties": true,
"description": "Serviceability (can this store deliver to the target), not proximity; use distance for near. Exactly one of point or address. Merchants that cannot evaluate it, Shopify stores included, return invalid_input.",
"maxProperties": 1,
"minProperties": 1,
"properties": {
"address": {
"allOf": [
{
"$ref": "#/$defs/d1"
},
{
"anyOf": [
{
"properties": {
"address_country": {
"minLength": 1,
"type": "string"
}
},
"required": [
"address_country"
]
},
{
"properties": {
"address_region": {
"minLength": 1,
"type": "string"
}
},
"required": [
"address_region"
]
},
{
"properties": {
"postal_code": {
"minLength": 1,
"type": "string"
}
},
"required": [
"postal_code"
]
}
],
"type": "object"
}
]
},
"point": {
"allOf": [
{
"$ref": "#/$defs/d3"
}
]
}
},
"propertyNames": {
"anyOf": [
{
"const": "point"
},
{
"const": "address"
},
{
"$ref": "#/$defs/d2"
}
]
},
"title": "Location Serves",
"type": "object"
}
]
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
]
},
"title": "Signals",
"type": "object"
}
},
"type": "object"
},
"d1": {
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
"d2": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d3": {
"description": "WGS 84 decimal degrees.",
"properties": {
"latitude": {
"maximum": 90,
"minimum": -90,
"type": "number"
},
"longitude": {
"maximum": 180,
"minimum": -180,
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"title": "Geo",
"type": "object"
}
},
"properties": {
"location": {
"$ref": "#/$defs/d0",
"allOf": [
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"location",
"shop"
],
"type": "object"
}
}lookup_locationsAnswer
Fetch shop's stores by store ID from search_locations — to re-read a store you saved, or check it against filters.items or distance. Same fields as search; results list which input IDs matched. Up to 10 IDs per call.
View tool JSON
{
"name": "lookup_locations",
"kind": "answer",
"impl": "imperative",
"description": "Fetch shop's stores by store ID from search_locations — to re-read a store you saved, or check it against filters.items or distance. Same fields as search; results list which input IDs matched. Up to 10 IDs per call.",
"inputSchema": {
"$defs": {
"d0": {
"properties": {
"context": {
"additionalProperties": true,
"allOf": [
{
"$ref": "#/$defs/d1"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d2"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"distance": {
"allOf": [
{
"additionalProperties": true,
"description": "Stores within max meters of an explicit center. Use coordinates the user or host gave; never derive them. The radius is never widened or clamped.",
"properties": {
"center": {
"allOf": [
{
"$ref": "#/$defs/d3"
}
]
},
"max": {
"description": "Inclusive radius in meters.",
"minimum": 0,
"type": "number"
}
},
"required": [
"center",
"max"
],
"title": "Location Distance",
"type": "object"
}
]
},
"filters": {
"additionalProperties": true,
"description": "Hard requirements; fields AND. A merchant rejects a filter it cannot evaluate with invalid_input rather than ignoring it; Shopify stores evaluate items only.",
"properties": {
"amenities": {
"description": "Exact amenity IDs, all required.",
"items": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
],
"examples": [
"dev.ucp.amenity.wi_fi",
"dev.ucp.amenity.parking",
"dev.ucp.amenity.shopping.in_store_pickup",
"dev.ucp.amenity.shopping.curbside_pickup"
],
"title": "Amenity Type"
},
"type": "array"
},
"hours": {
"properties": {
"open_at": {
"description": "RFC 3339 instant the store must be open at.",
"format": "date-time",
"pattern": "(?:[Zz]|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$",
"type": "string"
}
},
"required": [
"open_at"
],
"type": "object"
},
"items": {
"description": "Variant IDs from catalog results; returns stores that have all of them available, up to 10 items per call.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
},
"title": "Location Filter",
"type": "object"
},
"ids": {
"description": "Store IDs from search_locations, up to 10 per call.",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"serves": {
"allOf": [
{
"additionalProperties": true,
"description": "Serviceability (can this store deliver to the target), not proximity; use distance for near. Exactly one of point or address. Merchants that cannot evaluate it, Shopify stores included, return invalid_input.",
"maxProperties": 1,
"minProperties": 1,
"properties": {
"address": {
"allOf": [
{
"$ref": "#/$defs/d1"
},
{
"anyOf": [
{
"properties": {
"address_country": {
"minLength": 1,
"type": "string"
}
},
"required": [
"address_country"
]
},
{
"properties": {
"address_region": {
"minLength": 1,
"type": "string"
}
},
"required": [
"address_region"
]
},
{
"properties": {
"postal_code": {
"minLength": 1,
"type": "string"
}
},
"required": [
"postal_code"
]
}
],
"type": "object"
}
]
},
"point": {
"allOf": [
{
"$ref": "#/$defs/d3"
}
]
}
},
"propertyNames": {
"anyOf": [
{
"const": "point"
},
{
"const": "address"
},
{
"$ref": "#/$defs/d2"
}
]
},
"title": "Location Serves",
"type": "object"
}
]
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d2"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"ids"
],
"type": "object"
},
"d1": {
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
"d2": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d3": {
"description": "WGS 84 decimal degrees.",
"properties": {
"latitude": {
"maximum": 90,
"minimum": -90,
"type": "number"
},
"longitude": {
"maximum": 180,
"minimum": -180,
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"title": "Geo",
"type": "object"
}
},
"properties": {
"location": {
"$ref": "#/$defs/d0",
"allOf": [
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"location",
"shop"
],
"type": "object"
}
}create_cartAction
Create a cart only when asked to save items; interest is not permission. Use exact returned variant IDs/quantities. Use create_checkout for Review and pay. Does not order.
View tool JSON
{
"name": "create_cart",
"kind": "act",
"impl": "imperative",
"description": "Create a cart only when asked to save items; interest is not permission. Use exact returned variant IDs/quantities. Use create_checkout for Review and pay. Does not order.",
"inputSchema": {
"$defs": {
"d0": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
}
},
"properties": {
"cart": {
"allOf": [
{
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"name": "dev.ucp.shopping.cart",
"properties": {
"buyer": {
"additionalProperties": true,
"description": "Buyer details for personalized estimates.",
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"phone_number": {
"description": "Buyer phone in E.164.",
"type": "string"
}
},
"title": "Buyer",
"type": "object"
},
"context": {
"allOf": [
{
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d0"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
}
],
"description": "Soft pricing/availability/currency hints; geo-IP may fallback."
},
"line_items": {
"description": "On update send every line; omissions delete, not merge.",
"items": {
"description": "Uses parent cart/checkout currency.",
"properties": {
"item": {
"properties": {
"id": {
"description": "Copy exact returned variant ID; never rebuild/truncate.",
"type": "string"
},
"quantity_unit": {
"allOf": [
{
"allOf": [
{
"if": {
"properties": {
"unit": {
"const": "C62"
}
},
"required": [
"unit"
]
},
"properties": {
"display_text": {
"description": "Printable label for unrecognized units.",
"type": "string"
},
"scale": {
"default": 0,
"description": "One step = 10^-scale units; omitted=0; C62 needs 0.",
"maximum": 15,
"minimum": 0,
"type": "integer"
},
"unit": {
"description": "UN/CEFACT Rec 20 code, else stable opaque custom ID.",
"type": "string"
}
},
"required": [
"unit",
"display_text"
],
"then": {
"properties": {
"scale": {
"const": 0
}
}
},
"title": "Unit",
"type": "object"
},
{
"properties": {
"increment": {
"default": 1,
"description": "Step multiple (default 1); merchant may revise/reject, never reinterpret.",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
}
],
"description": "Sale basis is unit+scale, not display_text/increment.",
"title": "Quantity Unit"
}
],
"description": "Omit for merchant basis; else assert unit/scale. C62/0 = each."
}
},
"required": [
"id"
],
"title": "Item",
"type": "object"
},
"quantity": {
"description": "Integer sale-basis steps; missing quantity_unit is not each.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"title": "Line Item",
"type": "object"
},
"type": "array"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"line_items"
],
"title": "Cart",
"type": "object",
"version": "2026-08-25"
},
{
"properties": {
"discounts": {
"properties": {
"codes": {
"description": "Replace case-insensitively; [] clears all.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
],
"title": "Cart with Discount"
},
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"cart",
"shop"
],
"type": "object"
}
}get_cartAnswer
Read with the same shop/exact opaque ID before update or after an uncertain cart write.
View tool JSON
{
"name": "get_cart",
"kind": "answer",
"impl": "imperative",
"description": "Read with the same shop/exact opaque ID before update or after an uncertain cart write.",
"inputSchema": {
"properties": {
"id": {
"type": "string"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"shop"
],
"type": "object"
}
}update_cartAction
Replace full cart, not a patch. Read first; change only authorized fields; retain all other request fields, including empty objects/arrays. Response-only fields drop. Same shop/exact ID; check returned state. After uncertainty, read before retry.
View tool JSON
{
"name": "update_cart",
"kind": "act",
"impl": "imperative",
"description": "Replace full cart, not a patch. Read first; change only authorized fields; retain all other request fields, including empty objects/arrays. Response-only fields drop. Same shop/exact ID; check returned state. After uncertainty, read before retry.",
"inputSchema": {
"$defs": {
"d0": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
}
},
"properties": {
"cart": {
"allOf": [
{
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"name": "dev.ucp.shopping.cart",
"properties": {
"buyer": {
"additionalProperties": true,
"description": "Buyer details for personalized estimates.",
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"phone_number": {
"description": "Buyer phone in E.164.",
"type": "string"
}
},
"title": "Buyer",
"type": "object"
},
"context": {
"allOf": [
{
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d0"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
}
],
"description": "Soft pricing/availability/currency hints; geo-IP may fallback."
},
"line_items": {
"description": "On update send every line; omissions delete, not merge.",
"items": {
"description": "Uses parent cart/checkout currency.",
"properties": {
"id": {
"type": "string"
},
"item": {
"properties": {
"id": {
"description": "Copy exact returned variant ID; never rebuild/truncate.",
"type": "string"
},
"quantity_unit": {
"allOf": [
{
"allOf": [
{
"if": {
"properties": {
"unit": {
"const": "C62"
}
},
"required": [
"unit"
]
},
"properties": {
"display_text": {
"description": "Printable label for unrecognized units.",
"type": "string"
},
"scale": {
"default": 0,
"description": "One step = 10^-scale units; omitted=0; C62 needs 0.",
"maximum": 15,
"minimum": 0,
"type": "integer"
},
"unit": {
"description": "UN/CEFACT Rec 20 code, else stable opaque custom ID.",
"type": "string"
}
},
"required": [
"unit",
"display_text"
],
"then": {
"properties": {
"scale": {
"const": 0
}
}
},
"title": "Unit",
"type": "object"
},
{
"properties": {
"increment": {
"default": 1,
"description": "Step multiple (default 1); merchant may revise/reject, never reinterpret.",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
}
],
"description": "Sale basis is unit+scale, not display_text/increment.",
"title": "Quantity Unit"
}
],
"description": "Omit for merchant basis; else assert unit/scale. C62/0 = each."
}
},
"required": [
"id"
],
"title": "Item",
"type": "object"
},
"parent_id": {
"description": "Copy returned parent line ID unchanged.",
"type": "string"
},
"quantity": {
"description": "Integer sale-basis steps; missing quantity_unit is not each.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"title": "Line Item",
"type": "object"
},
"type": "array"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"line_items"
],
"title": "Cart",
"type": "object",
"version": "2026-08-25"
},
{
"properties": {
"discounts": {
"properties": {
"codes": {
"description": "Replace case-insensitively; [] clears all.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
],
"title": "Cart with Discount"
},
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"id": {
"type": "string"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"cart",
"shop"
],
"type": "object"
}
}create_checkoutSensitive Action
Prepare Shop/UCP checkout only when asked. No separate spend request is needed. Use exact variant IDs/quantities. Share continue_url unchanged for Review and pay, including requires_escalation. Never recreate: get/update its ID. Address incomplete via update. Complete ready_for_complete only after buyer approval. Creates no order.
View tool JSON
{
"name": "create_checkout",
"kind": "transact",
"impl": "imperative",
"description": "Prepare Shop/UCP checkout only when asked. No separate spend request is needed. Use exact variant IDs/quantities. Share continue_url unchanged for Review and pay, including requires_escalation. Never recreate: get/update its ID. Address incomplete via update. Complete ready_for_complete only after buyer approval. Creates no order.",
"inputSchema": {
"$defs": {
"d0": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"name": "dev.ucp.shopping.checkout",
"properties": {
"buyer": {
"additionalProperties": true,
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"phone_number": {
"description": "Buyer phone in E.164.",
"type": "string"
}
},
"title": "Buyer",
"type": "object"
},
"context": {
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d10"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d10"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"line_items": {
"description": "On update send every line; omissions delete, never merge.",
"items": {
"description": "Uses parent cart/checkout currency.",
"properties": {
"item": {
"properties": {
"id": {
"description": "Copy exact returned variant ID; never rebuild/truncate.",
"type": "string"
},
"quantity_unit": {
"allOf": [
{
"allOf": [
{
"if": {
"properties": {
"unit": {
"const": "C62"
}
},
"required": [
"unit"
]
},
"properties": {
"display_text": {
"description": "Printable label for unrecognized units.",
"type": "string"
},
"scale": {
"default": 0,
"description": "One step = 10^-scale units; omitted=0; C62 needs 0.",
"maximum": 15,
"minimum": 0,
"type": "integer"
},
"unit": {
"description": "UN/CEFACT Rec 20 code, else stable opaque custom ID.",
"type": "string"
}
},
"required": [
"unit",
"display_text"
],
"then": {
"properties": {
"scale": {
"const": 0
}
}
},
"title": "Unit",
"type": "object"
},
{
"properties": {
"increment": {
"default": 1,
"description": "Step multiple (default 1); merchant may revise/reject, never reinterpret.",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
}
],
"description": "Sale basis is unit+scale, not display_text/increment.",
"title": "Quantity Unit"
}
],
"description": "Omit for merchant basis; else assert unit/scale. C62/0 = each."
}
},
"required": [
"id"
],
"title": "Item",
"type": "object"
},
"quantity": {
"description": "Integer sale-basis steps; missing quantity_unit is not each.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"title": "Line Item",
"type": "object"
},
"type": "array"
},
"payment": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Only after shopper selects an instrument.",
"properties": {
"instruments": {
"items": {
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"properties": {
"billing_address": {
"properties": {
"address_country": {
"$ref": "#/$defs/d1"
},
"address_locality": {
"$ref": "#/$defs/d2"
},
"address_region": {
"$ref": "#/$defs/d3"
},
"extended_address": {
"$ref": "#/$defs/d4"
},
"first_name": {
"$ref": "#/$defs/d5"
},
"last_name": {
"$ref": "#/$defs/d6"
},
"phone_number": {
"$ref": "#/$defs/d7"
},
"postal_code": {
"$ref": "#/$defs/d8"
},
"street_address": {
"$ref": "#/$defs/d9"
}
},
"title": "Postal Address",
"type": "object"
},
"credential": {
"additionalProperties": true,
"description": "Shape defined by the handler.",
"properties": {
"type": {
"description": "Type the handler requires.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Payment Credential",
"type": "object"
},
"display": {
"type": "object"
},
"handler_id": {
"description": "Merchant-advertised handler ID.",
"type": "string"
},
"id": {
"description": "Opaque; never reuse across merchants.",
"type": "string"
},
"type": {
"description": "Handler category, e.g. card.",
"type": "string"
}
},
"required": [
"id",
"handler_id",
"type"
],
"title": "Payment Instrument",
"type": "object"
},
{
"properties": {
"selected": {
"description": "True only on the one shopper-approved instrument.",
"type": "boolean"
}
},
"type": "object"
}
],
"title": "Selected Payment Instrument"
},
"type": "array"
}
},
"title": "Payment",
"type": "object"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d10"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"line_items"
],
"title": "Checkout",
"type": "object",
"version": "2026-08-25"
},
"d1": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"d10": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d2": {
"type": "string"
},
"d3": {
"type": "string"
},
"d4": {
"type": "string"
},
"d5": {
"type": "string"
},
"d6": {
"type": "string"
},
"d7": {
"type": "string"
},
"d8": {
"type": "string"
},
"d9": {
"type": "string"
}
},
"properties": {
"checkout": {
"allOf": [
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {
"discounts": {
"properties": {
"codes": {
"description": "Replace case-insensitively; [] clears all.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
],
"title": "Checkout with Discount"
},
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {
"fulfillment": {
"allOf": [
{
"properties": {
"methods": {
"description": "Methods covering the checkout's line items.",
"items": {
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "shipping"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"destinations": {
"description": "Platform-authored shipping addresses.",
"items": {
"allOf": [
{
"properties": {
"address_country": {
"$ref": "#/$defs/d1"
},
"address_locality": {
"$ref": "#/$defs/d2"
},
"address_region": {
"$ref": "#/$defs/d3"
},
"extended_address": {
"$ref": "#/$defs/d4"
},
"first_name": {
"$ref": "#/$defs/d5"
},
"last_name": {
"$ref": "#/$defs/d6"
},
"phone_number": {
"$ref": "#/$defs/d7"
},
"postal_code": {
"$ref": "#/$defs/d8"
},
"street_address": {
"$ref": "#/$defs/d9"
}
},
"title": "Postal Address",
"type": "object"
},
{
"properties": {
"id": {
"description": "Platform-assigned ID for this address.",
"type": "string"
},
"type": {
"const": "shipping_address",
"type": "string"
}
},
"required": [],
"type": "object"
}
],
"title": "Shipping Destination",
"type": "object"
},
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "pickup"
}
},
"required": [
"type"
]
},
"then": {
"properties": {}
}
}
],
"dependentRequired": {
"destinations": [
"type"
]
},
"properties": {
"groups": {
"description": "Merchant groups; select returned options.",
"items": {
"additionalProperties": true,
"properties": {
"selected_option_id": {
"description": "Option ID returned for this group.",
"type": [
"string",
"null"
]
}
},
"required": [],
"title": "Fulfillment Group",
"type": "object"
},
"type": "array"
},
"selected_destination_id": {
"description": "Merchant-scoped; need not be returned.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Shipping, pickup, or another supported type.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Fulfillment Method",
"type": "object"
},
"type": "array"
}
},
"title": "Fulfillment",
"type": "object"
}
]
}
},
"type": "object"
}
],
"title": "Checkout with Fulfillment"
},
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"checkout",
"shop"
],
"type": "object"
}
}get_checkoutAnswer
Read with the same shop/exact opaque ID before update/completion or after an uncertain write. continue_url is Review and pay, not a product page/purchase proof.
View tool JSON
{
"name": "get_checkout",
"kind": "answer",
"impl": "imperative",
"description": "Read with the same shop/exact opaque ID before update/completion or after an uncertain write. continue_url is Review and pay, not a product page/purchase proof.",
"inputSchema": {
"properties": {
"id": {
"type": "string"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"shop"
],
"type": "object"
}
}update_checkoutSensitive Action
Replace full checkout, not patch/payment. Read first; change only authorized fields; retain all other request fields, including empty objects/arrays. Response-only fields drop. Same shop/exact ID; check status/messages/continue_url. After uncertainty, read before retry.
View tool JSON
{
"name": "update_checkout",
"kind": "transact",
"impl": "imperative",
"description": "Replace full checkout, not patch/payment. Read first; change only authorized fields; retain all other request fields, including empty objects/arrays. Response-only fields drop. Same shop/exact ID; check status/messages/continue_url. After uncertainty, read before retry.",
"inputSchema": {
"$defs": {
"d0": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"name": "dev.ucp.shopping.checkout",
"properties": {
"buyer": {
"additionalProperties": true,
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"phone_number": {
"description": "Buyer phone in E.164.",
"type": "string"
}
},
"title": "Buyer",
"type": "object"
},
"context": {
"additionalProperties": true,
"allOf": [
{
"additionalProperties": true,
"description": "Coarse locality; not an address.",
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_region": {
"type": "string"
},
"postal_code": {
"type": "string"
}
},
"title": "Locality",
"type": "object"
},
{
"additionalProperties": true,
"properties": {
"currency": {
"description": "ISO 4217 preference/filter currency; verify output.",
"type": "string"
},
"eligibility": {
"description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
"items": {
"$ref": "#/$defs/d10"
},
"type": "array",
"uniqueItems": true
},
"intent": {
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
},
"language": {
"description": "BCP 47 preference, e.g. fr-CA.",
"type": "string"
},
"location": {
"description": "Opaque merchant location ID, not locality.",
"type": "string"
},
"payment": {
"description": "Advertised handlers, most preferred first; ignore unknowns.",
"items": {
"properties": {
"handler": {
"allOf": [
{
"$ref": "#/$defs/d10"
}
],
"description": "Merchant ucp.payment_handlers key."
},
"types": {
"description": "Instrument types, most preferred first; ignore unknowns.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"handler"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Soft relevance/localization; checkout wins.",
"title": "Context",
"type": "object"
},
"line_items": {
"description": "On update send every line; omissions delete, never merge.",
"items": {
"description": "Uses parent cart/checkout currency.",
"properties": {
"id": {
"type": "string"
},
"item": {
"properties": {
"id": {
"description": "Copy exact returned variant ID; never rebuild/truncate.",
"type": "string"
},
"quantity_unit": {
"allOf": [
{
"allOf": [
{
"if": {
"properties": {
"unit": {
"const": "C62"
}
},
"required": [
"unit"
]
},
"properties": {
"display_text": {
"description": "Printable label for unrecognized units.",
"type": "string"
},
"scale": {
"default": 0,
"description": "One step = 10^-scale units; omitted=0; C62 needs 0.",
"maximum": 15,
"minimum": 0,
"type": "integer"
},
"unit": {
"description": "UN/CEFACT Rec 20 code, else stable opaque custom ID.",
"type": "string"
}
},
"required": [
"unit",
"display_text"
],
"then": {
"properties": {
"scale": {
"const": 0
}
}
},
"title": "Unit",
"type": "object"
},
{
"properties": {
"increment": {
"default": 1,
"description": "Step multiple (default 1); merchant may revise/reject, never reinterpret.",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
}
],
"description": "Sale basis is unit+scale, not display_text/increment.",
"title": "Quantity Unit"
}
],
"description": "Omit for merchant basis; else assert unit/scale. C62/0 = each."
}
},
"required": [
"id"
],
"title": "Item",
"type": "object"
},
"parent_id": {
"description": "Copy returned parent line ID unchanged.",
"type": "string"
},
"quantity": {
"description": "Integer sale-basis steps; missing quantity_unit is not each.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"title": "Line Item",
"type": "object"
},
"type": "array"
},
"payment": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Only after shopper selects an instrument.",
"properties": {
"instruments": {
"items": {
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"properties": {
"billing_address": {
"properties": {
"address_country": {
"$ref": "#/$defs/d1"
},
"address_locality": {
"$ref": "#/$defs/d2"
},
"address_region": {
"$ref": "#/$defs/d3"
},
"extended_address": {
"$ref": "#/$defs/d4"
},
"first_name": {
"$ref": "#/$defs/d5"
},
"last_name": {
"$ref": "#/$defs/d6"
},
"phone_number": {
"$ref": "#/$defs/d7"
},
"postal_code": {
"$ref": "#/$defs/d8"
},
"street_address": {
"$ref": "#/$defs/d9"
}
},
"title": "Postal Address",
"type": "object"
},
"credential": {
"additionalProperties": true,
"description": "Shape defined by the handler.",
"properties": {
"type": {
"description": "Type the handler requires.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Payment Credential",
"type": "object"
},
"display": {
"type": "object"
},
"handler_id": {
"description": "Merchant-advertised handler ID.",
"type": "string"
},
"id": {
"description": "Opaque; never reuse across merchants.",
"type": "string"
},
"type": {
"description": "Handler category, e.g. card.",
"type": "string"
}
},
"required": [
"id",
"handler_id",
"type"
],
"title": "Payment Instrument",
"type": "object"
},
{
"properties": {
"selected": {
"description": "True only on the one shopper-approved instrument.",
"type": "boolean"
}
},
"type": "object"
}
],
"title": "Selected Payment Instrument"
},
"type": "array"
}
},
"title": "Payment",
"type": "object"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"$ref": "#/$defs/d10"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"line_items"
],
"title": "Checkout",
"type": "object",
"version": "2026-08-25"
},
"d1": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"d10": {
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
},
"d2": {
"type": "string"
},
"d3": {
"type": "string"
},
"d4": {
"type": "string"
},
"d5": {
"type": "string"
},
"d6": {
"type": "string"
},
"d7": {
"type": "string"
},
"d8": {
"type": "string"
},
"d9": {
"type": "string"
}
},
"properties": {
"checkout": {
"allOf": [
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {
"discounts": {
"properties": {
"codes": {
"description": "Replace case-insensitively; [] clears all.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
],
"title": "Checkout with Discount"
},
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {
"fulfillment": {
"allOf": [
{
"properties": {
"methods": {
"description": "Methods covering the checkout's line items.",
"items": {
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "shipping"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"destinations": {
"description": "Platform-authored shipping addresses.",
"items": {
"allOf": [
{
"properties": {
"address_country": {
"$ref": "#/$defs/d1"
},
"address_locality": {
"$ref": "#/$defs/d2"
},
"address_region": {
"$ref": "#/$defs/d3"
},
"extended_address": {
"$ref": "#/$defs/d4"
},
"first_name": {
"$ref": "#/$defs/d5"
},
"last_name": {
"$ref": "#/$defs/d6"
},
"phone_number": {
"$ref": "#/$defs/d7"
},
"postal_code": {
"$ref": "#/$defs/d8"
},
"street_address": {
"$ref": "#/$defs/d9"
}
},
"title": "Postal Address",
"type": "object"
},
{
"properties": {
"id": {
"description": "Platform-assigned ID for this address.",
"type": "string"
},
"type": {
"const": "shipping_address",
"type": "string"
}
},
"required": [],
"type": "object"
}
],
"title": "Shipping Destination",
"type": "object"
},
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "pickup"
}
},
"required": [
"type"
]
},
"then": {
"properties": {}
}
}
],
"dependentRequired": {
"destinations": [
"type"
]
},
"properties": {
"groups": {
"description": "Merchant groups; select returned options.",
"items": {
"additionalProperties": true,
"properties": {
"id": {
"description": "On update, merchant-returned group ID.",
"type": "string"
},
"selected_option_id": {
"description": "Option ID returned for this group.",
"type": [
"string",
"null"
]
}
},
"required": [
"id"
],
"title": "Fulfillment Group",
"type": "object"
},
"type": "array"
},
"id": {
"description": "On update, merchant-returned method ID.",
"type": "string"
},
"line_item_ids": {
"description": "On update, returned line IDs fulfilled by this method.",
"items": {
"type": "string"
},
"type": "array"
},
"selected_destination_id": {
"description": "Merchant-scoped; need not be returned.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Shipping, pickup, or another supported type.",
"type": "string"
}
},
"required": [
"line_item_ids"
],
"title": "Fulfillment Method",
"type": "object"
},
"type": "array"
}
},
"title": "Fulfillment",
"type": "object"
}
]
}
},
"type": "object"
}
],
"title": "Checkout with Fulfillment"
},
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"id": {
"type": "string"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"checkout",
"shop"
],
"type": "object"
}
}complete_checkoutSensitive Action
Send user-approved payment to the same shop/exact checkout ID with one exact offered instrument selected:true. Only completed + order proves purchase. After uncertainty, read get_checkout; never repeat completion or start a replacement purchase.
View tool JSON
{
"name": "complete_checkout",
"kind": "transact",
"impl": "imperative",
"description": "Send user-approved payment to the same shop/exact checkout ID with one exact offered instrument selected:true. Only completed + order proves purchase. After uncertainty, read get_checkout; never repeat completion or start a replacement purchase.",
"inputSchema": {
"$defs": {
"d0": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"name": "dev.ucp.shopping.checkout",
"properties": {
"payment": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Only after shopper selects an instrument.",
"properties": {
"instruments": {
"items": {
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"properties": {
"billing_address": {
"properties": {
"address_country": {
"description": "ISO 3166-1 alpha-2, e.g. US.",
"type": "string"
},
"address_locality": {
"type": "string"
},
"address_region": {
"type": "string"
},
"extended_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"street_address": {
"type": "string"
}
},
"title": "Postal Address",
"type": "object"
},
"credential": {
"additionalProperties": true,
"description": "Shape defined by the handler.",
"properties": {
"type": {
"description": "Type the handler requires.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Payment Credential",
"type": "object"
},
"display": {
"type": "object"
},
"handler_id": {
"description": "Merchant-advertised handler ID.",
"type": "string"
},
"id": {
"description": "Opaque; never reuse across merchants.",
"type": "string"
},
"type": {
"description": "Handler category, e.g. card.",
"type": "string"
}
},
"required": [
"id",
"handler_id",
"type"
],
"title": "Payment Instrument",
"type": "object"
},
{
"properties": {
"selected": {
"description": "True only on the one shopper-approved instrument.",
"type": "boolean"
}
},
"type": "object"
}
],
"title": "Selected Payment Instrument"
},
"type": "array"
}
},
"title": "Payment",
"type": "object"
},
"signals": {
"additionalProperties": true,
"description": "Observed/verified platform facts; no buyer claims.",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string"
},
"dev.ucp.user_agent": {
"type": "string"
}
},
"propertyNames": {
"allOf": [
{
"description": "Reverse domain, 2+ segments.",
"examples": [
"dev.ucp.shopping.checkout",
"dev.ucp.common.identity_linking",
"com.example.loyalty_gold",
"com.example-shop.checkout",
"com.2example.cart",
"uk.co.example-shop.checkout",
"xn--p1ai.example.checkout"
],
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"title": "Reverse Domain Name",
"type": "string"
}
]
},
"title": "Signals",
"type": "object"
}
},
"required": [
"payment"
],
"title": "Checkout",
"type": "object",
"version": "2026-08-25"
}
},
"properties": {
"checkout": {
"allOf": [
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {},
"type": "object"
}
],
"title": "Checkout with Discount"
},
{
"allOf": [
{
"$ref": "#/$defs/d0"
},
{
"properties": {},
"type": "object"
}
],
"title": "Checkout with Fulfillment"
},
{
"not": {
"required": [
"attribution"
]
}
}
],
"type": "object"
},
"id": {
"type": "string"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"shop": {
"description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"checkout",
"shop"
],
"type": "object"
}
}search_ordersAnswer
Search the signed-in buyer's Shop-tracked orders and shipments from any store. Returns in-progress orders by default; set filters.status to all to search the full order history.
View tool JSON
{
"name": "search_orders",
"kind": "answer",
"impl": "imperative",
"description": "Search the signed-in buyer's Shop-tracked orders and shipments from any store. Returns in-progress orders by default; set filters.status to all to search the full order history.",
"inputSchema": {
"properties": {
"orders": {
"properties": {
"filters": {
"description": "Narrow the search; fields AND.",
"properties": {
"date": {
"description": "Order placement dates, YYYY-MM-DD.",
"properties": {
"from": {
"format": "date",
"type": "string"
},
"to": {
"format": "date",
"type": "string"
}
},
"title": "Date Range",
"type": "object"
},
"status": {
"default": "in_progress",
"description": "in_progress: orders still in progress. all: the full order history.",
"enum": [
"in_progress",
"all"
],
"type": "string"
}
},
"title": "Search Filters",
"type": "object"
},
"pagination": {
"description": "Page orders and standalone shipments together.",
"properties": {
"cursor": {
"description": "Pass unchanged with the same query and filters.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 5,
"description": "Page size. Defaults to 5; maximum 10.",
"maximum": 10,
"minimum": 1,
"type": "integer"
}
},
"title": "Pagination Request",
"type": "object"
},
"query": {
"description": "Merchant, item, or order number; omit to list.",
"maxLength": 200,
"type": "string"
}
},
"title": "Search Request",
"type": "object"
}
},
"required": [
"orders"
],
"type": "object"
}
}get_accountAnswer
Read signed-in Shop account, addresses, spend permissions, cards. For missing checkout delivery, copy one addresses[] entry unchanged into fulfillment destinations and select its id; preferred_address_id is default. buyer.email is display-only, never checkout input. Missing is unknown (messages say why); empty spend_permissions means none is set.
View tool JSON
{
"name": "get_account",
"kind": "answer",
"impl": "imperative",
"description": "Read signed-in Shop account, addresses, spend permissions, cards. For missing checkout delivery, copy one addresses[] entry unchanged into fulfillment destinations and select its id; preferred_address_id is default. buyer.email is display-only, never checkout input. Missing is unknown (messages say why); empty spend_permissions means none is set.",
"inputSchema": {
"properties": {},
"required": [],
"type": "object"
}
}create_spend_requestAction
Request buyer approval for a purchase where the agent enters a payment credential into a website's checkout form using a browser. Provide the purchase terms and spending limit; name a saved card, or omit it to use the account's preferred card. Share the returned continue_url unchanged for review and approval. This does not pay or place an order.
View tool JSON
{
"name": "create_spend_request",
"kind": "act",
"impl": "imperative",
"description": "Request buyer approval for a purchase where the agent enters a payment credential into a website's checkout form using a browser. Provide the purchase terms and spending limit; name a saved card, or omit it to use the account's preferred card. Share the returned continue_url unchanged for review and approval. This does not pay or place an order.",
"inputSchema": {
"$defs": {
"d0": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"properties": {
"meta": {
"properties": {
"idempotency-key": {
"description": "Reuse only for exact retries. Update/cancel derive a key if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"spend_request": {
"properties": {
"approval_limit": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Positive spending limit in currency minor units.",
"minimum": 1
},
"business": {
"properties": {
"country": {
"description": "Omit unless the site states it.",
"maxLength": 2,
"minLength": 2,
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"name": {
"minLength": 1,
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"name",
"url"
],
"type": "object"
},
"context": {
"properties": {
"address_country": false,
"address_region": false,
"currency": false,
"eligibility": false,
"intent": {
"allOf": [
{
"description": "Relevance hint, e.g. 'gift under $50'.",
"type": "string"
}
],
"description": "Describe the purchase and rationale (100-500 chars); the buyer reads this when approving."
},
"language": false,
"location": false,
"payment": false,
"postal_code": false
},
"required": [
"intent"
],
"type": "object"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"instrument_id": {
"description": "Saved card chosen by the buyer; omit to use get_account.preferred_instrument_id.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"type": "string"
},
"line_items": {
"items": {
"properties": {
"item": {
"properties": {
"price": {
"$ref": "#/$defs/d0"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"price"
],
"type": "object"
},
"quantity": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"type": "object"
},
"type": "array"
},
"shipping_address": {
"properties": {
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"address_region": {
"type": "string"
},
"extended_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"street_address": {
"type": "string"
}
},
"type": "object"
},
"totals": {
"contains": {
"properties": {
"type": {
"const": "total"
}
},
"required": [
"type"
],
"type": "object"
},
"items": {
"allOf": [
{
"if": {
"properties": {
"type": {
"enum": [
"discount",
"items_discount"
]
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"amount": {
"exclusiveMaximum": 0
}
}
}
},
{
"if": {
"properties": {
"type": {
"enum": [
"subtotal",
"fulfillment",
"tax",
"fee"
]
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"amount": {
"minimum": 0
}
}
}
}
],
"properties": {
"amount": {
"description": "Signed ISO 4217 minor units; discounts negative.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"title": "Signed Amount",
"type": "integer"
},
"type": {
"minLength": 1,
"type": "string"
}
},
"required": [
"type",
"amount"
],
"type": "object"
},
"maxContains": 1,
"minContains": 1,
"minItems": 1,
"type": "array"
}
},
"required": [
"business",
"currency",
"totals",
"approval_limit",
"context"
],
"type": "object"
}
},
"required": [
"spend_request"
],
"type": "object"
}
}get_spend_requestSensitive Action
Read a spend request, optionally requesting an issued card. Omit include to read status and terms only. Set include to "card" to obtain the issued card after the buyer approves the request.
View tool JSON
{
"name": "get_spend_request",
"kind": "transact",
"impl": "imperative",
"description": "Read a spend request, optionally requesting an issued card. Omit include to read status and terms only. Set include to \"card\" to obtain the issued card after the buyer approves the request.",
"inputSchema": {
"properties": {
"id": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"type": "string"
},
"include": {
"description": "Optional credential selection. Currently supported: card. Omit to read status and terms only.",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
}
}update_spend_requestAction
Update the request's address, items, totals or spending limit. Omitted fields stay unchanged. Wallet decides whether its current state allows the update.
View tool JSON
{
"name": "update_spend_request",
"kind": "act",
"impl": "imperative",
"description": "Update the request's address, items, totals or spending limit. Omitted fields stay unchanged. Wallet decides whether its current state allows the update.",
"inputSchema": {
"$defs": {
"d0": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"properties": {
"id": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"type": "string"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "Reuse only for exact retries. Update/cancel derive a key if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"spend_request": {
"minProperties": 1,
"properties": {
"approval_limit": {
"allOf": [
{
"$ref": "#/$defs/d0"
}
],
"description": "Positive spending limit in currency minor units.",
"minimum": 1
},
"business": false,
"context": false,
"currency": false,
"instrument_id": false,
"line_items": {
"items": {
"properties": {
"item": {
"properties": {
"price": {
"$ref": "#/$defs/d0"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"price"
],
"type": "object"
},
"quantity": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"item",
"quantity"
],
"type": "object"
},
"type": "array"
},
"shipping_address": {
"properties": {
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"address_region": {
"type": "string"
},
"extended_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"street_address": {
"type": "string"
}
},
"type": "object"
},
"totals": {
"contains": {
"properties": {
"type": {
"const": "total"
}
},
"required": [
"type"
],
"type": "object"
},
"items": {
"allOf": [
{
"if": {
"properties": {
"type": {
"enum": [
"discount",
"items_discount"
]
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"amount": {
"exclusiveMaximum": 0
}
}
}
},
{
"if": {
"properties": {
"type": {
"enum": [
"subtotal",
"fulfillment",
"tax",
"fee"
]
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"amount": {
"minimum": 0
}
}
}
}
],
"properties": {
"amount": {
"description": "Signed ISO 4217 minor units; discounts negative.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"title": "Signed Amount",
"type": "integer"
},
"type": {
"minLength": 1,
"type": "string"
}
},
"required": [
"type",
"amount"
],
"type": "object"
},
"maxContains": 1,
"minContains": 1,
"minItems": 1,
"type": "array"
}
},
"type": "object"
}
},
"required": [
"id",
"spend_request"
],
"type": "object"
}
}cancel_spend_requestSensitive Action
Cancel the spend request; this does not cancel/refund the purchase or revoke an issued credential.
View tool JSON
{
"name": "cancel_spend_request",
"kind": "transact",
"impl": "imperative",
"description": "Cancel the spend request; this does not cancel/refund the purchase or revoke an issued credential.",
"inputSchema": {
"properties": {
"id": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"type": "string"
},
"meta": {
"properties": {
"idempotency-key": {
"description": "Reuse only for exact retries. Update/cancel derive a key if omitted.",
"format": "uuid",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"id"
],
"type": "object"
}
}complete_spend_requestAction
Report the purchase attempt's outcome as success or error. Include order details when available, or failure information for an error. This records your report, not payment confirmation.
View tool JSON
{
"name": "complete_spend_request",
"kind": "act",
"impl": "imperative",
"description": "Report the purchase attempt's outcome as success or error. Include order details when available, or failure information for an error. This records your report, not payment confirmation.",
"inputSchema": {
"properties": {
"id": {
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"type": "string"
},
"result": {
"anyOf": [
{
"properties": {
"failure_code": false,
"message": false,
"order": {
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"type": "string"
},
"permalink_url": {
"format": "uri",
"type": "string"
},
"total": {
"description": "ISO 4217 minor units: USD2, JPY0, KWD3.",
"maximum": 9007199254740991,
"minimum": 0,
"title": "Amount",
"type": "integer"
}
},
"type": "object"
},
"status": {
"const": "success",
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
{
"properties": {
"failure_code": {
"description": "Observed failure code. Examples are not exhaustive.",
"examples": [
"captcha",
"anti_bot_script",
"cdn_block",
"waf_block",
"dns_block",
"rate_limited",
"login_required",
"3ds_challenge",
"page_inaccessible",
"timeout",
"site_error",
"payment_declined",
"other"
],
"type": "string"
},
"message": {
"type": "string"
},
"order": false,
"status": {
"const": "error",
"type": "string"
}
},
"required": [
"status",
"failure_code"
],
"type": "object"
}
],
"description": "Observed outcome: success may include known order fields; error requires failure_code and may include message. No credentials.",
"type": "object"
}
},
"required": [
"id",
"result"
],
"type": "object"
}
}