{ "endpoint": "https://ridefox.com/api/ucp/mcp", "captured": "2026-10-27", "method": "initialize + tools/list (anonymous, no tool called; roadmap#992)", "protocol_version": "2025-06-18", "server_info": { "name": "universal-commerce", "version": "0.1.0" }, "result": { "tools": [ { "name": "get_checkout", "description": "Returns details about the checkout, including line items, totals, and any applicable discounts or taxes.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "id": { "type": "string", "description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'" } }, "required": [ "meta", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Checkout or receipt response", "description": "The open checkout, or a receipt when the checkout has already been submitted.", "oneOf": [ { "type": "object", "title": "Checkout response", "description": "Structured checkout content returned while the checkout is still open.", "required": [ "ucp", "id", "line_items", "status", "currency", "totals", "links" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status.", "enum": [ "incomplete", "requires_escalation", "ready_for_complete", "canceled" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "payment": { "type": "object", "description": "Payment information for the checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments available to or selected by the buyer.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handler_id": { "type": "string" }, "type": { "type": "string" }, "selected": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } }, "billing_address": { "type": "object", "description": "Mailing address fields.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } }, "display": { "type": [ "object", "null" ], "description": "Handler-specific display data (for example card brand and last digits).", "additionalProperties": true } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } }, { "type": "object", "title": "Receipt response", "description": "Structured receipt content returned once the checkout has been submitted.", "required": [ "ucp", "id", "status", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status after submission.", "enum": [ "complete_in_progress", "completed" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "payment": { "type": "object", "description": "Payment summary for the completed checkout.", "additionalProperties": true, "properties": { "handlers": { "type": "object", "description": "Payment handlers accepted by the merchant.", "additionalProperties": true }, "instruments": { "type": "array", "description": "Payment instruments used for the order.", "items": { "type": "object", "additionalProperties": true } } } }, "order": { "type": "object", "description": "Order confirmation. Present once the checkout has completed.", "required": [ "id", "permalink_url" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The order GID." }, "label": { "type": "string", "description": "The buyer-facing order label." }, "permalink_url": { "type": "string", "format": "uri", "description": "The order status URL." } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } ] } }, { "name": "create_checkout", "description": "Creates a checkout. Returns checkout details, including line items, totals, and any applicable discounts or taxes.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "checkout": { "type": "object", "description": "Checkout properties.", "properties": { "payment": { "type": "object", "description": "Payment information for this checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets).", "items": { "type": "object", "required": [ "id", "handler_id", "type" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "handler_id": { "const": "apple-pay" } }, "required": [ "handler_id" ] }, "then": { "required": [ "billing_address", "credential" ], "properties": { "type": { "const": "card" }, "credential": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type", "payment_data" ] } } }, "else": { "properties": { "credential": { "required": [ "type" ], "properties": { "type": { "not": { "const": "apple_pay_token" } } } } } } } ], "properties": { "id": { "type": "string", "description": "A unique identifier for this payment instrument instance." }, "handler_id": { "type": "string", "description": "Identifier of the payment handler that was used to generate this instrument." }, "type": { "type": "string", "description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card." }, "billing_address": { "type": "object", "description": "Billing address for the instrument.", "additionalProperties": true, "properties": { "street_address": { "type": "string", "description": "Street address of the billing address." }, "extended_address": { "type": "string", "description": "Extended address of the billing address such as an apartment number, C/O, or alternative name." }, "address_locality": { "type": "string", "description": "Locality of the billing address." }, "address_region": { "type": "string", "description": "Region of the billing address." }, "postal_code": { "type": "string", "description": "Postal code of the billing address." }, "address_country": { "type": "string", "description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format." }, "first_name": { "type": "string", "description": "First name of the contact associated with the billing address." }, "last_name": { "type": "string", "description": "Last name of the contact associated with the billing address." }, "phone_number": { "type": "string", "description": "Phone number of the contact associated with the billing address." } } }, "credential": { "type": "object", "description": "Payment credential payload to process the transaction for this instrument.", "additionalProperties": true, "allOf": [ { "if": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type" ] }, "then": { "required": [ "type", "payment_data" ], "properties": { "type": { "const": "apple_pay_token" }, "payment_data": { "type": "object", "required": [ "version", "data", "signature", "header" ], "additionalProperties": true, "properties": { "version": { "type": "string" }, "data": { "type": "string" }, "signature": { "type": "string" }, "header": { "type": "object", "required": [ "public_key_hash", "transaction_id" ], "anyOf": [ { "required": [ "ephemeral_public_key" ] }, { "required": [ "wrapped_key" ] } ], "additionalProperties": true, "properties": { "ephemeral_public_key": { "type": "string" }, "wrapped_key": { "type": "string" }, "public_key_hash": { "type": "string" }, "transaction_id": { "type": "string" }, "application_data": { "type": "string" } } } } }, "transaction_identifier": { "type": "string" } } }, "else": { "required": [ "type" ] } } ], "properties": { "token": { "type": "string", "description": "Opaque payment token value, required except when restating a platform-listed instrument (e.g., a Shop Pay wallet card) whose token the platform re-derives from the instrument id." }, "type": { "type": "string", "description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)." }, "payment_data": { "type": "object" }, "transaction_identifier": { "type": "string" }, "approval_id": { "type": "string", "description": "Identifier of the payment approval authorizing this credential, as returned by the approvals API. Required for shop_pay credentials when the merchant requires payment approvals." } } }, "display": { "type": "object", "description": "Display information for this payment instrument.", "additionalProperties": true, "properties": { "brand": { "type": "string", "description": "Card brand (e.g., visa, mastercard), when available." }, "last_digits": { "type": "string", "description": "Last 4 digits of the card, when available." }, "expiry_month": { "type": "integer", "description": "Card expiry month (1-12). Required for card instruments." }, "expiry_year": { "type": "integer", "description": "Card expiry year. Required for card instruments." }, "rich_text_description": { "type": "string", "description": "Rich text description of the payment instrument for display purposes." }, "rich_card_art": { "type": "string", "description": "Rich card art URL or identifier for the payment instrument." }, "funding_source": { "type": "string", "enum": [ "debit", "credit", "prepaid", "store" ], "description": "How the card is funded, as reported by Apple Pay." } } }, "selected": { "type": "boolean", "description": "Whether this instrument is the currently selected for the checkout." } } } } } }, "line_items": { "type": "array", "description": "Items to add to the cart or checkout. Required when creating a new cart or checkout.", "items": { "type": "object", "required": [ "item", "quantity" ], "properties": { "id": { "type": "string", "description": "The ID of the line item to update." }, "quantity": { "type": "integer" }, "item": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Product Variant ID to add or update." } } } } } }, "buyer": { "type": "object", "description": "Information about the buyer including email and phone number.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Per-purpose buyer consent decisions, keyed by reverse-DNS identifiers. Omission leaves existing choices unchanged.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." }, "segments": { "type": "object", "description": "One level of refinements. Marketing supports dev.ucp.consent.marketing.email and dev.ucp.consent.marketing.sms; a segment overrides its parent.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." } } } } } } } } }, "context": { "type": "object", "description": "Provisional context hints for localization and pricing. Used when authoritative data (e.g., shipping address) is missing; higher-resolution data supersedes these values and unsupported hints may be ignored without error.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country hint for localization." }, "address_region": { "type": "string", "description": "Region/state hint for localization." }, "postal_code": { "type": "string", "description": "Postal code hint for localization." }, "intent": { "type": "string", "description": "Context describing buyer's intent." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')." }, "eligibility": { "type": "array", "description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar.", "items": { "type": "string", "description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty').", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters).", "properties": { "referring_domain": { "type": "string", "description": "Domain that referred the buyer to the merchant's storefront." }, "click_id_tag": { "type": "string", "description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')." }, "click_id_value": { "type": "string", "description": "Click identifier value matching click_id_tag." }, "activity_id_tag": { "type": "string", "description": "Activity identifier parameter name." }, "activity_id_value": { "type": "string", "description": "Activity identifier value matching activity_id_tag." }, "utm_campaign": { "type": "string", "description": "UTM campaign parameter." }, "utm_source": { "type": "string", "description": "UTM source parameter." }, "utm_medium": { "type": "string", "description": "UTM medium parameter." }, "utm_content": { "type": "string", "description": "UTM content parameter." }, "utm_term": { "type": "string", "description": "UTM term parameter." } } }, "cart_id": { "type": "string", "description": "Cart ID to convert to checkout. When provided, the business uses cart contents (line_items, context, buyer) and ignores overlapping fields in the checkout payload. line_items is still required: pass an empty array (\"line_items\": []). Format: 'gid://shopify/Cart/abc123?key=secret'" }, "fulfillment": { "type": "object", "description": "Information about the fulfillment.", "properties": { "methods": { "type": "array", "description": "The methods of fulfillment.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "selected_destination_id": { "type": "string", "description": "ID of the selected destination." }, "destinations": { "type": "array", "description": "The destinations to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "The groups to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "selected_option_id": { "type": "string" } } } } }, "required": [ "type" ] } } } }, "discounts": { "type": "object", "description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code.", "properties": { "codes": { "type": "array", "description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.", "items": { "type": "string" } } } } }, "required": [ "line_items" ] } }, "required": [ "meta", "checkout" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Checkout response", "description": "Structured checkout content returned while the checkout is still open.", "required": [ "ucp", "id", "line_items", "status", "currency", "totals", "links" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status.", "enum": [ "incomplete", "requires_escalation", "ready_for_complete", "canceled" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "payment": { "type": "object", "description": "Payment information for the checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments available to or selected by the buyer.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handler_id": { "type": "string" }, "type": { "type": "string" }, "selected": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } }, "billing_address": { "type": "object", "description": "Mailing address fields.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } }, "display": { "type": [ "object", "null" ], "description": "Handler-specific display data (for example card brand and last digits).", "additionalProperties": true } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "update_checkout", "description": "Updates a checkout. Returns checkout details, including line items, totals, and any applicable discounts or taxes.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "checkout": { "type": "object", "description": "Checkout properties.", "properties": { "payment": { "type": "object", "description": "Payment information for this checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets).", "items": { "type": "object", "required": [ "id", "handler_id", "type" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "handler_id": { "const": "apple-pay" } }, "required": [ "handler_id" ] }, "then": { "required": [ "billing_address", "credential" ], "properties": { "type": { "const": "card" }, "credential": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type", "payment_data" ] } } }, "else": { "properties": { "credential": { "required": [ "type" ], "properties": { "type": { "not": { "const": "apple_pay_token" } } } } } } } ], "properties": { "id": { "type": "string", "description": "A unique identifier for this payment instrument instance." }, "handler_id": { "type": "string", "description": "Identifier of the payment handler that was used to generate this instrument." }, "type": { "type": "string", "description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card." }, "billing_address": { "type": "object", "description": "Billing address for the instrument.", "additionalProperties": true, "properties": { "street_address": { "type": "string", "description": "Street address of the billing address." }, "extended_address": { "type": "string", "description": "Extended address of the billing address such as an apartment number, C/O, or alternative name." }, "address_locality": { "type": "string", "description": "Locality of the billing address." }, "address_region": { "type": "string", "description": "Region of the billing address." }, "postal_code": { "type": "string", "description": "Postal code of the billing address." }, "address_country": { "type": "string", "description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format." }, "first_name": { "type": "string", "description": "First name of the contact associated with the billing address." }, "last_name": { "type": "string", "description": "Last name of the contact associated with the billing address." }, "phone_number": { "type": "string", "description": "Phone number of the contact associated with the billing address." } } }, "credential": { "type": "object", "description": "Payment credential payload to process the transaction for this instrument.", "additionalProperties": true, "allOf": [ { "if": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type" ] }, "then": { "required": [ "type", "payment_data" ], "properties": { "type": { "const": "apple_pay_token" }, "payment_data": { "type": "object", "required": [ "version", "data", "signature", "header" ], "additionalProperties": true, "properties": { "version": { "type": "string" }, "data": { "type": "string" }, "signature": { "type": "string" }, "header": { "type": "object", "required": [ "public_key_hash", "transaction_id" ], "anyOf": [ { "required": [ "ephemeral_public_key" ] }, { "required": [ "wrapped_key" ] } ], "additionalProperties": true, "properties": { "ephemeral_public_key": { "type": "string" }, "wrapped_key": { "type": "string" }, "public_key_hash": { "type": "string" }, "transaction_id": { "type": "string" }, "application_data": { "type": "string" } } } } }, "transaction_identifier": { "type": "string" } } }, "else": { "required": [ "type" ] } } ], "properties": { "token": { "type": "string", "description": "Opaque payment token value, required except when restating a platform-listed instrument (e.g., a Shop Pay wallet card) whose token the platform re-derives from the instrument id." }, "type": { "type": "string", "description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)." }, "payment_data": { "type": "object" }, "transaction_identifier": { "type": "string" }, "approval_id": { "type": "string", "description": "Identifier of the payment approval authorizing this credential, as returned by the approvals API. Required for shop_pay credentials when the merchant requires payment approvals." } } }, "display": { "type": "object", "description": "Display information for this payment instrument.", "additionalProperties": true, "properties": { "brand": { "type": "string", "description": "Card brand (e.g., visa, mastercard), when available." }, "last_digits": { "type": "string", "description": "Last 4 digits of the card, when available." }, "expiry_month": { "type": "integer", "description": "Card expiry month (1-12). Required for card instruments." }, "expiry_year": { "type": "integer", "description": "Card expiry year. Required for card instruments." }, "rich_text_description": { "type": "string", "description": "Rich text description of the payment instrument for display purposes." }, "rich_card_art": { "type": "string", "description": "Rich card art URL or identifier for the payment instrument." }, "funding_source": { "type": "string", "enum": [ "debit", "credit", "prepaid", "store" ], "description": "How the card is funded, as reported by Apple Pay." } } }, "selected": { "type": "boolean", "description": "Whether this instrument is the currently selected for the checkout." } } } } } }, "line_items": { "type": "array", "description": "Items to add to the cart or checkout. Required when creating a new cart or checkout.", "items": { "type": "object", "required": [ "item", "quantity" ], "properties": { "id": { "type": "string", "description": "The ID of the line item to update." }, "quantity": { "type": "integer" }, "item": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Product Variant ID to add or update." } } } } } }, "buyer": { "type": "object", "description": "Information about the buyer including email and phone number.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Per-purpose buyer consent decisions, keyed by reverse-DNS identifiers. Omission leaves existing choices unchanged.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." }, "segments": { "type": "object", "description": "One level of refinements. Marketing supports dev.ucp.consent.marketing.email and dev.ucp.consent.marketing.sms; a segment overrides its parent.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." } } } } } } } } }, "context": { "type": "object", "description": "Provisional context hints for localization and pricing. Used when authoritative data (e.g., shipping address) is missing; higher-resolution data supersedes these values and unsupported hints may be ignored without error.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country hint for localization." }, "address_region": { "type": "string", "description": "Region/state hint for localization." }, "postal_code": { "type": "string", "description": "Postal code hint for localization." }, "intent": { "type": "string", "description": "Context describing buyer's intent." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')." }, "eligibility": { "type": "array", "description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar.", "items": { "type": "string", "description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty').", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters).", "properties": { "referring_domain": { "type": "string", "description": "Domain that referred the buyer to the merchant's storefront." }, "click_id_tag": { "type": "string", "description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')." }, "click_id_value": { "type": "string", "description": "Click identifier value matching click_id_tag." }, "activity_id_tag": { "type": "string", "description": "Activity identifier parameter name." }, "activity_id_value": { "type": "string", "description": "Activity identifier value matching activity_id_tag." }, "utm_campaign": { "type": "string", "description": "UTM campaign parameter." }, "utm_source": { "type": "string", "description": "UTM source parameter." }, "utm_medium": { "type": "string", "description": "UTM medium parameter." }, "utm_content": { "type": "string", "description": "UTM content parameter." }, "utm_term": { "type": "string", "description": "UTM term parameter." } } }, "fulfillment": { "type": "object", "description": "Information about the fulfillment.", "properties": { "methods": { "type": "array", "description": "The methods of fulfillment.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "line_item_ids": { "type": "array", "description": "The line item ids to fulfill.", "items": { "type": "string" } }, "selected_destination_id": { "type": "string", "description": "ID of the selected destination." }, "destinations": { "type": "array", "description": "The destinations to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "The groups to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "selected_option_id": { "type": "string" } }, "required": [ "id" ] } } }, "required": [ "line_item_ids" ] } } } }, "discounts": { "type": "object", "description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code.", "properties": { "codes": { "type": "array", "description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.", "items": { "type": "string" } } } } }, "required": [ "line_items" ] }, "id": { "type": "string", "description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'" } }, "required": [ "meta", "checkout", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Checkout response", "description": "Structured checkout content returned while the checkout is still open.", "required": [ "ucp", "id", "line_items", "status", "currency", "totals", "links" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status.", "enum": [ "incomplete", "requires_escalation", "ready_for_complete", "canceled" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "payment": { "type": "object", "description": "Payment information for the checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments available to or selected by the buyer.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handler_id": { "type": "string" }, "type": { "type": "string" }, "selected": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } }, "billing_address": { "type": "object", "description": "Mailing address fields.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } }, "display": { "type": [ "object", "null" ], "description": "Handler-specific display data (for example card brand and last digits).", "additionalProperties": true } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "complete_checkout", "description": "Completes a checkout and returns the checkout result. Returns details about the completed checkout, including order ID, Thank You Page URL, or any errors encountered.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] }, "idempotency-key": { "type": "string", "description": "An idempotency key for completing the checkout." } }, "required": [ "ucp-agent", "idempotency-key" ] }, "checkout": { "type": "object", "description": "Checkout properties.", "properties": { "payment": { "type": "object", "description": "Payment information for this checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets).", "items": { "type": "object", "required": [ "id", "handler_id", "type" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "handler_id": { "const": "apple-pay" } }, "required": [ "handler_id" ] }, "then": { "required": [ "billing_address", "credential" ], "properties": { "type": { "const": "card" }, "credential": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type", "payment_data" ] } } }, "else": { "properties": { "credential": { "required": [ "type" ], "properties": { "type": { "not": { "const": "apple_pay_token" } } } } } } } ], "properties": { "id": { "type": "string", "description": "A unique identifier for this payment instrument instance." }, "handler_id": { "type": "string", "description": "Identifier of the payment handler that was used to generate this instrument." }, "type": { "type": "string", "description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card." }, "billing_address": { "type": "object", "description": "Billing address for the instrument.", "additionalProperties": true, "properties": { "street_address": { "type": "string", "description": "Street address of the billing address." }, "extended_address": { "type": "string", "description": "Extended address of the billing address such as an apartment number, C/O, or alternative name." }, "address_locality": { "type": "string", "description": "Locality of the billing address." }, "address_region": { "type": "string", "description": "Region of the billing address." }, "postal_code": { "type": "string", "description": "Postal code of the billing address." }, "address_country": { "type": "string", "description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format." }, "first_name": { "type": "string", "description": "First name of the contact associated with the billing address." }, "last_name": { "type": "string", "description": "Last name of the contact associated with the billing address." }, "phone_number": { "type": "string", "description": "Phone number of the contact associated with the billing address." } } }, "credential": { "type": "object", "description": "Payment credential payload to process the transaction for this instrument.", "additionalProperties": true, "allOf": [ { "if": { "properties": { "type": { "const": "apple_pay_token" } }, "required": [ "type" ] }, "then": { "required": [ "type", "payment_data" ], "properties": { "type": { "const": "apple_pay_token" }, "payment_data": { "type": "object", "required": [ "version", "data", "signature", "header" ], "additionalProperties": true, "properties": { "version": { "type": "string" }, "data": { "type": "string" }, "signature": { "type": "string" }, "header": { "type": "object", "required": [ "public_key_hash", "transaction_id" ], "anyOf": [ { "required": [ "ephemeral_public_key" ] }, { "required": [ "wrapped_key" ] } ], "additionalProperties": true, "properties": { "ephemeral_public_key": { "type": "string" }, "wrapped_key": { "type": "string" }, "public_key_hash": { "type": "string" }, "transaction_id": { "type": "string" }, "application_data": { "type": "string" } } } } }, "transaction_identifier": { "type": "string" } } }, "else": { "required": [ "type" ] } } ], "properties": { "token": { "type": "string", "description": "Opaque payment token value, required except when restating a platform-listed instrument (e.g., a Shop Pay wallet card) whose token the platform re-derives from the instrument id." }, "type": { "type": "string", "description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)." }, "payment_data": { "type": "object" }, "transaction_identifier": { "type": "string" }, "approval_id": { "type": "string", "description": "Identifier of the payment approval authorizing this credential, as returned by the approvals API. Required for shop_pay credentials when the merchant requires payment approvals." } } }, "display": { "type": "object", "description": "Display information for this payment instrument.", "additionalProperties": true, "properties": { "brand": { "type": "string", "description": "Card brand (e.g., visa, mastercard), when available." }, "last_digits": { "type": "string", "description": "Last 4 digits of the card, when available." }, "expiry_month": { "type": "integer", "description": "Card expiry month (1-12). Required for card instruments." }, "expiry_year": { "type": "integer", "description": "Card expiry year. Required for card instruments." }, "rich_text_description": { "type": "string", "description": "Rich text description of the payment instrument for display purposes." }, "rich_card_art": { "type": "string", "description": "Rich card art URL or identifier for the payment instrument." }, "funding_source": { "type": "string", "enum": [ "debit", "credit", "prepaid", "store" ], "description": "How the card is funded, as reported by Apple Pay." } } }, "selected": { "type": "boolean", "description": "Whether this instrument is the currently selected for the checkout." } } } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters).", "properties": { "referring_domain": { "type": "string", "description": "Domain that referred the buyer to the merchant's storefront." }, "click_id_tag": { "type": "string", "description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')." }, "click_id_value": { "type": "string", "description": "Click identifier value matching click_id_tag." }, "activity_id_tag": { "type": "string", "description": "Activity identifier parameter name." }, "activity_id_value": { "type": "string", "description": "Activity identifier value matching activity_id_tag." }, "utm_campaign": { "type": "string", "description": "UTM campaign parameter." }, "utm_source": { "type": "string", "description": "UTM source parameter." }, "utm_medium": { "type": "string", "description": "UTM medium parameter." }, "utm_content": { "type": "string", "description": "UTM content parameter." }, "utm_term": { "type": "string", "description": "UTM term parameter." } } }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "consent": { "type": "object", "description": "Per-purpose buyer consent decisions, keyed by reverse-DNS identifiers. Omission leaves existing choices unchanged.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." }, "segments": { "type": "object", "description": "One level of refinements. Marketing supports dev.ucp.consent.marketing.email and dev.ucp.consent.marketing.sms; a segment overrides its parent.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." } } } } } } } } } }, "required": [ "payment" ] }, "id": { "type": "string", "description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'" } }, "required": [ "meta", "id", "checkout" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Checkout or receipt response", "description": "The open checkout, or a receipt when the checkout has already been submitted.", "oneOf": [ { "type": "object", "title": "Checkout response", "description": "Structured checkout content returned while the checkout is still open.", "required": [ "ucp", "id", "line_items", "status", "currency", "totals", "links" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status.", "enum": [ "incomplete", "requires_escalation", "ready_for_complete", "canceled" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "payment": { "type": "object", "description": "Payment information for the checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments available to or selected by the buyer.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handler_id": { "type": "string" }, "type": { "type": "string" }, "selected": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } }, "billing_address": { "type": "object", "description": "Mailing address fields.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } }, "display": { "type": [ "object", "null" ], "description": "Handler-specific display data (for example card brand and last digits).", "additionalProperties": true } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } }, { "type": "object", "title": "Receipt response", "description": "Structured receipt content returned once the checkout has been submitted.", "required": [ "ucp", "id", "status", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status after submission.", "enum": [ "complete_in_progress", "completed" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "payment": { "type": "object", "description": "Payment summary for the completed checkout.", "additionalProperties": true, "properties": { "handlers": { "type": "object", "description": "Payment handlers accepted by the merchant.", "additionalProperties": true }, "instruments": { "type": "array", "description": "Payment instruments used for the order.", "items": { "type": "object", "additionalProperties": true } } } }, "order": { "type": "object", "description": "Order confirmation. Present once the checkout has completed.", "required": [ "id", "permalink_url" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The order GID." }, "label": { "type": "string", "description": "The buyer-facing order label." }, "permalink_url": { "type": "string", "format": "uri", "description": "The order status URL." } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } ] } }, { "name": "cancel_checkout", "description": "Cancels a checkout.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "id": { "type": "string", "description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'" } }, "required": [ "meta", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Checkout response", "description": "Structured checkout content returned while the checkout is still open.", "required": [ "ucp", "id", "line_items", "status", "currency", "totals", "links" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Checkout GID." }, "status": { "type": "string", "description": "The checkout status.", "enum": [ "incomplete", "requires_escalation", "ready_for_complete", "canceled" ] }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "payment": { "type": "object", "description": "Payment information for the checkout.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "description": "Payment instruments available to or selected by the buyer.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handler_id": { "type": "string" }, "type": { "type": "string" }, "selected": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } }, "billing_address": { "type": "object", "description": "Mailing address fields.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } }, "display": { "type": [ "object", "null" ], "description": "Handler-specific display data (for example card brand and last digits).", "additionalProperties": true } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "get_cart", "description": "Get the cart contents\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "id": { "type": "string", "description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'" } }, "required": [ "meta", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Cart response", "description": "Structured cart content.", "required": [ "ucp", "id", "line_items", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Cart GID." }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "create_cart", "description": "Creates a new cart\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "cart": { "type": "object", "description": "Cart properties.", "properties": { "line_items": { "type": "array", "description": "Items to add to the cart or checkout. Required when creating a new cart or checkout.", "items": { "type": "object", "required": [ "item", "quantity" ], "properties": { "id": { "type": "string", "description": "The ID of the line item to update." }, "quantity": { "type": "integer" }, "item": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Product Variant ID to add or update." } } } } } }, "buyer": { "type": "object", "description": "Information about the buyer including email and phone number.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Per-purpose buyer consent decisions, keyed by reverse-DNS identifiers. Omission leaves existing choices unchanged.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." }, "segments": { "type": "object", "description": "One level of refinements. Marketing supports dev.ucp.consent.marketing.email and dev.ucp.consent.marketing.sms; a segment overrides its parent.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." } } } } } } } } }, "context": { "type": "object", "description": "Provisional context hints for localization and pricing. Used when authoritative data (e.g., shipping address) is missing; higher-resolution data supersedes these values and unsupported hints may be ignored without error.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country hint for localization." }, "address_region": { "type": "string", "description": "Region/state hint for localization." }, "postal_code": { "type": "string", "description": "Postal code hint for localization." }, "intent": { "type": "string", "description": "Context describing buyer's intent." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')." }, "eligibility": { "type": "array", "description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar.", "items": { "type": "string", "description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty').", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters). Forwarded to the cart for downstream reporting.", "properties": { "referring_domain": { "type": "string", "description": "Domain that referred the buyer to the merchant's storefront." }, "click_id_tag": { "type": "string", "description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')." }, "click_id_value": { "type": "string", "description": "Click identifier value matching click_id_tag." }, "activity_id_tag": { "type": "string", "description": "Activity identifier parameter name." }, "activity_id_value": { "type": "string", "description": "Activity identifier value matching activity_id_tag." }, "utm_campaign": { "type": "string", "description": "UTM campaign parameter." }, "utm_source": { "type": "string", "description": "UTM source parameter." }, "utm_medium": { "type": "string", "description": "UTM medium parameter." }, "utm_content": { "type": "string", "description": "UTM content parameter." }, "utm_term": { "type": "string", "description": "UTM term parameter." } } }, "fulfillment": { "type": "object", "description": "Information about the fulfillment.", "properties": { "methods": { "type": "array", "description": "The methods of fulfillment.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "selected_destination_id": { "type": "string", "description": "ID of the selected destination." }, "destinations": { "type": "array", "description": "The destinations to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "The groups to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "selected_option_id": { "type": "string" } } } } }, "required": [ "type" ] } } } }, "discounts": { "type": "object", "description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code.", "properties": { "codes": { "type": "array", "description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.", "items": { "type": "string" } } } } }, "required": [ "line_items" ] } }, "required": [ "meta", "cart" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Cart response", "description": "Structured cart content.", "required": [ "ucp", "id", "line_items", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Cart GID." }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "update_cart", "description": "Perform updates to a cart.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "cart": { "type": "object", "description": "Cart properties.", "properties": { "line_items": { "type": "array", "description": "Items to add to the cart or checkout. Required when creating a new cart or checkout.", "items": { "type": "object", "required": [ "item", "quantity" ], "properties": { "id": { "type": "string", "description": "The ID of the line item to update." }, "quantity": { "type": "integer" }, "item": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Product Variant ID to add or update." } } } } } }, "buyer": { "type": "object", "description": "Information about the buyer including email and phone number.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Per-purpose buyer consent decisions, keyed by reverse-DNS identifiers. Omission leaves existing choices unchanged.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." }, "segments": { "type": "object", "description": "One level of refinements. Marketing supports dev.ucp.consent.marketing.email and dev.ucp.consent.marketing.sms; a segment overrides its parent.", "additionalProperties": { "type": "object", "required": [ "granted", "source" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean", "description": "Whether consent is granted." }, "source": { "type": "string", "enum": [ "business", "platform" ], "description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices." } } } } } } } } }, "context": { "type": "object", "description": "Provisional context hints for localization and pricing. Used when authoritative data (e.g., shipping address) is missing; higher-resolution data supersedes these values and unsupported hints may be ignored without error.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country hint for localization." }, "address_region": { "type": "string", "description": "Region/state hint for localization." }, "postal_code": { "type": "string", "description": "Postal code hint for localization." }, "intent": { "type": "string", "description": "Context describing buyer's intent." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')." }, "eligibility": { "type": "array", "description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar.", "items": { "type": "string", "description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty').", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters). Forwarded to the cart for downstream reporting.", "properties": { "referring_domain": { "type": "string", "description": "Domain that referred the buyer to the merchant's storefront." }, "click_id_tag": { "type": "string", "description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')." }, "click_id_value": { "type": "string", "description": "Click identifier value matching click_id_tag." }, "activity_id_tag": { "type": "string", "description": "Activity identifier parameter name." }, "activity_id_value": { "type": "string", "description": "Activity identifier value matching activity_id_tag." }, "utm_campaign": { "type": "string", "description": "UTM campaign parameter." }, "utm_source": { "type": "string", "description": "UTM source parameter." }, "utm_medium": { "type": "string", "description": "UTM medium parameter." }, "utm_content": { "type": "string", "description": "UTM content parameter." }, "utm_term": { "type": "string", "description": "UTM term parameter." } } }, "fulfillment": { "type": "object", "description": "Information about the fulfillment.", "properties": { "methods": { "type": "array", "description": "The methods of fulfillment.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "line_item_ids": { "type": "array", "description": "The line item ids to fulfill.", "items": { "type": "string" } }, "selected_destination_id": { "type": "string", "description": "ID of the selected destination." }, "destinations": { "type": "array", "description": "The destinations to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "The groups to fulfill to.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "selected_option_id": { "type": "string" } }, "required": [ "id" ] } } }, "required": [ "line_item_ids" ] } } } }, "discounts": { "type": "object", "description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code.", "properties": { "codes": { "type": "array", "description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.", "items": { "type": "string" } } } } }, "required": [ "line_items" ] }, "id": { "type": "string", "description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'" } }, "required": [ "meta", "cart", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Cart response", "description": "Structured cart content.", "required": [ "ucp", "id", "line_items", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Cart GID." }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "cancel_cart", "description": "Cancels a cart.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "id": { "type": "string", "description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'" } }, "required": [ "meta", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Cart response", "description": "Structured cart content.", "required": [ "ucp", "id", "line_items", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version", "status", "services", "capabilities", "payment_handlers" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Cart GID." }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "description": "Information about the buyer.", "additionalProperties": true, "properties": { "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "consent": { "type": "object", "description": "Current buyer consent decisions and business defaults, keyed by purpose.", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" }, "segments": { "type": "object", "additionalProperties": { "type": "object", "required": [ "granted", "source", "description" ], "additionalProperties": true, "properties": { "granted": { "type": "boolean" }, "source": { "type": "string", "enum": [ "business", "platform" ] }, "description": { "type": "string" } } } } } } } } }, "line_items": { "type": "array", "description": "Line items in the checkout.", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item ID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "integer", "description": "The line item quantity." }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "parent_id": { "type": "string", "description": "The parent line item ID for nested line items." } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the checkout expires." }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "links": { "type": "array", "description": "Merchant policy links relevant to the checkout.", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The policy URL." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } }, "continue_url": { "type": "string", "format": "uri", "description": "The URL where the buyer can continue checkout." }, "fulfillment": { "type": "object", "description": "Fulfillment methods, destinations, delivery groups, and delivery options.", "additionalProperties": true, "properties": { "methods": { "type": "array", "description": "Fulfillment methods available for the checkout or cart.", "items": { "type": "object", "required": [ "id", "type", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "line_item_ids": { "type": "array", "description": "Line item IDs covered by this fulfillment method.", "items": { "type": "string" } }, "selected_destination_id": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "description": "Destinations available for this fulfillment method.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string" }, "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "address_country": { "type": "string" } } } }, "groups": { "type": "array", "description": "Delivery groups for this fulfillment method.", "items": { "type": "object", "required": [ "id", "line_item_ids" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "selected_option_id": { "type": [ "string", "null" ] }, "options": { "type": "array", "description": "Delivery options available for the group.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "description": "Buyer-facing description of the delivery option.", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string" }, "amount": { "type": "integer", "description": "The amount in minor currency units." } } } } } } } } } } } } } } }, "discounts": { "type": "object", "description": "Discount codes and applied discounts for the checkout or cart.", "additionalProperties": true, "properties": { "codes": { "type": "array", "description": "Discount codes submitted for the checkout or cart.", "items": { "type": "string" } }, "applied": { "type": "array", "description": "Discounts applied to the checkout or cart, including automatic discounts.", "items": { "type": "object", "required": [ "title", "amount" ], "additionalProperties": true, "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "description": "The discount amount in minor currency units." }, "method": { "type": "string", "description": "How the discount is allocated across the targeted items.", "enum": [ "each", "across", "one" ] }, "automatic": { "type": "boolean" }, "allocations": { "type": "array", "description": "Line item or fulfillment total allocations of the discount.", "items": { "type": "object", "required": [ "path", "amount" ], "additionalProperties": true, "properties": { "path": { "type": "string", "description": "JSONPath to the discounted line item or total." }, "amount": { "type": "integer", "description": "The allocated amount in minor currency units." } } } } } } } } } } } }, { "name": "get_order", "description": "Get the details of an order\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "id": { "type": "string", "description": "The ID of the order. Format: 'gid://shopify/Order/123'" } }, "required": [ "meta", "id" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Order response", "description": "Structured order content.", "required": [ "ucp", "id", "permalink_url", "line_items", "fulfillment", "currency", "totals" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "id": { "type": "string", "description": "The Shopify Order GID." }, "label": { "type": "string", "description": "The buyer-facing order name or confirmation number." }, "checkout_id": { "type": "string", "description": "The checkout ID, when the order has checkout linkage." }, "permalink_url": { "type": "string", "description": "The order status page URL." }, "currency": { "type": "string", "description": "The presentment currency code (ISO 4217)." }, "buyer": { "type": "object", "additionalProperties": true, "properties": { "email": { "type": "string" }, "phone_number": { "type": "string" } } }, "payment": { "type": "object", "description": "Payment instruments used for the order.", "additionalProperties": true, "properties": { "instruments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "attribution": { "type": "object", "description": "Marketing attribution context for the buyer's session.", "additionalProperties": true, "properties": { "referring_domain": { "type": "string" }, "click_id_tag": { "type": "string" }, "click_id_value": { "type": "string" }, "activity_id_tag": { "type": "string" }, "activity_id_value": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "item", "quantity", "totals", "status" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item GID." }, "item": { "type": "object", "description": "The merchandise item for a line item.", "required": [ "id", "title", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The product variant GID." }, "title": { "type": "string", "description": "The item title." }, "price": { "type": "integer", "description": "The unit price in minor currency units." }, "image_url": { "type": "string", "format": "uri", "description": "The item image URL." } } }, "quantity": { "type": "object", "required": [ "total", "fulfilled" ], "additionalProperties": true, "properties": { "original": { "type": "integer" }, "total": { "type": "integer" }, "fulfilled": { "type": "integer" } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "status": { "type": "string", "enum": [ "processing", "partial", "fulfilled", "removed" ] }, "parent_id": { "type": "string", "description": "The line item group GID, for bundled items." } } } }, "fulfillment": { "type": "object", "additionalProperties": true, "properties": { "expectations": { "type": "array", "items": { "type": "object", "required": [ "id", "line_items", "method_type", "destination" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "quantity" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item GID." }, "quantity": { "type": "integer" } } } }, "method_type": { "type": "string" }, "destination": { "type": "object", "additionalProperties": true }, "description": { "type": "string" }, "fulfillable_on": { "type": "string" }, "selected_option": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "carrier_identifier": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "plain": { "type": "string" } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } } } } } } }, "events": { "type": "array", "items": { "type": "object", "required": [ "id", "occurred_at", "type", "line_items" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "occurred_at": { "type": "string", "description": "RFC 3339 timestamp." }, "type": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "quantity" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item GID." }, "quantity": { "type": "integer" } } } }, "tracking_number": { "type": "string" }, "tracking_url": { "type": "string" }, "carrier": { "type": "string" }, "description": { "type": "string" } } } } } }, "adjustments": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "occurred_at", "status" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "occurred_at": { "type": "string", "description": "RFC 3339 timestamp." }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "quantity" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The line item GID." }, "quantity": { "type": "integer" } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "description": { "type": "string" } } } }, "totals": { "type": "array", "description": "Monetary totals in minor currency units.", "items": { "type": "object", "required": [ "type", "amount" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses may use additional values, which always carry `display_text` (Shopify emits `duty`)." }, "amount": { "type": "integer", "description": "The amount in minor currency units. Discount totals are negative." }, "display_text": { "type": "string", "description": "Buyer-facing label for the total." } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } }, { "name": "search_catalog", "description": "Search for products from the online store, hosted on Shopify.\n\nThis tool can be used to search for products using natural language queries, specific filter criteria, or both.\nAt least one of query or filters must be provided.\n\nResults are paginated, with initial results limited to improve experience.\nUse the pagination.cursor from the response to fetch additional pages when users request more results.\n\nResponse conforms to the UCP catalog search capability (dev.ucp.shopping.catalog.search).\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "catalog": { "type": "object", "description": "Catalog search parameters.", "properties": { "query": { "type": "string", "description": "Search query string." }, "context": { "type": "object", "description": "Buyer signals for localization and personalization.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format." }, "address_region": { "type": "string", "description": "Region or state." }, "postal_code": { "type": "string", "description": "Postal code." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "intent": { "type": "string", "description": "Buyer intent." } } }, "signals": { "type": "object", "description": "Platform environment data.", "additionalProperties": true, "properties": { "dev.ucp.buyer_ip": { "type": "string", "description": "Buyer IP address." }, "dev.ucp.user_agent": { "type": "string", "description": "Buyer user agent." } } }, "filters": { "type": "object", "description": "Narrowing criteria for catalog results.", "additionalProperties": true, "properties": { "categories": { "type": "array", "description": "Category filters combined with OR logic.", "items": { "type": "string" } }, "price": { "type": "object", "description": "Price range filter.", "properties": { "min": { "type": "integer", "description": "Minimum price in minor currency units." }, "max": { "type": "integer", "description": "Maximum price in minor currency units." } } }, "available": { "type": "boolean", "description": "Filter by availability. Default true (only sale-ready items).", "default": true } } }, "pagination": { "type": "object", "description": "Pagination parameters.", "properties": { "cursor": { "type": "string", "description": "Pagination cursor." }, "limit": { "type": "integer", "description": "Number of results to return.", "default": 10, "minimum": 1 } } } } } }, "required": [ "meta", "catalog" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Catalog search response", "description": "Products matching a catalog search.", "required": [ "ucp", "products" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "products": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "price_range", "variants" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "values" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "label" ], "additionalProperties": true, "properties": { "label": { "type": "string" }, "available": { "type": "boolean" }, "exists": { "type": "boolean" } } } } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "list_price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "availability": { "type": "object", "additionalProperties": true, "properties": { "available": { "type": "boolean" } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "label" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "label": { "type": "string" } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "sku": { "type": "string" }, "requires": { "type": "object", "additionalProperties": true, "properties": { "shipping": { "type": "boolean" }, "selling_plan": { "type": "boolean" } } }, "checkout_url": { "type": "string", "description": "A cart permalink for the variant on this store." } } } }, "url": { "type": "string", "description": "The online store URL." }, "handle": { "type": "string" }, "list_price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "categories": { "type": "array", "items": { "type": "object", "required": [ "value" ], "additionalProperties": true, "properties": { "value": { "type": "string" }, "taxonomy": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "gift_card": { "type": "boolean" }, "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "url": { "type": "string" }, "media": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } } } } } } }, "pagination": { "type": "object", "required": [ "has_next_page" ], "additionalProperties": true, "properties": { "has_next_page": { "type": "boolean" }, "cursor": { "type": "string", "description": "Opaque cursor for the next page." }, "total_count": { "type": "integer" } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } }, { "name": "lookup_catalog", "description": "Look up multiple products or variants by identifier.\nUse this tool to resolve multiple product/variant IDs in a single request.\n\nSupports:\n- Product IDs (gid://shopify/Product/...): Returns product with match: \"featured\"\n- Variant IDs (gid://shopify/ProductVariant/...): Returns parent product with the exact variant\n\nResults are grouped by product. Each variant includes an inputs array showing\nwhich request ID resolved to it and whether the match was exact or featured.\nIn versions that require input correlations, only matched variants are returned.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n\nMaximum 10 IDs per request.\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "catalog": { "type": "object", "description": "Catalog lookup parameters.", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "Product IDs to look up.", "items": { "type": "string" }, "minItems": 1, "maxItems": 10 }, "context": { "type": "object", "description": "Buyer signals for localization and personalization.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format." }, "address_region": { "type": "string", "description": "Region or state." }, "postal_code": { "type": "string", "description": "Postal code." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "intent": { "type": "string", "description": "Buyer intent." } } }, "signals": { "type": "object", "description": "Platform environment data.", "additionalProperties": true, "properties": { "dev.ucp.buyer_ip": { "type": "string", "description": "Buyer IP address." }, "dev.ucp.user_agent": { "type": "string", "description": "Buyer user agent." } } }, "filters": { "type": "object", "description": "Narrowing criteria for catalog results.", "additionalProperties": true, "properties": { "categories": { "type": "array", "description": "Category filters combined with OR logic.", "items": { "type": "string" } }, "price": { "type": "object", "description": "Price range filter.", "properties": { "min": { "type": "integer", "description": "Minimum price in minor currency units." }, "max": { "type": "integer", "description": "Maximum price in minor currency units." } } }, "available": { "type": "boolean", "description": "Filter by availability. Default true (only sale-ready items).", "default": true } } } } } }, "required": [ "meta", "catalog" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Catalog lookup response", "description": "Products resolved from the requested identifiers.", "required": [ "ucp", "products" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "products": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "price_range", "variants" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "values" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "label" ], "additionalProperties": true, "properties": { "label": { "type": "string" }, "available": { "type": "boolean" }, "exists": { "type": "boolean" } } } } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "list_price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "availability": { "type": "object", "additionalProperties": true, "properties": { "available": { "type": "boolean" } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "label" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "label": { "type": "string" } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "sku": { "type": "string" }, "inputs": { "type": "array", "description": "The requested identifiers that resolved to this variant.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "match": { "type": "string", "description": "`exact` for a variant id, `featured` for a product id or URL." } } } }, "requires": { "type": "object", "additionalProperties": true, "properties": { "shipping": { "type": "boolean" }, "selling_plan": { "type": "boolean" } } }, "checkout_url": { "type": "string", "description": "A cart permalink for the variant on this store." } } } }, "url": { "type": "string", "description": "The online store URL." }, "handle": { "type": "string" }, "list_price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "categories": { "type": "array", "items": { "type": "object", "required": [ "value" ], "additionalProperties": true, "properties": { "value": { "type": "string" }, "taxonomy": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "gift_card": { "type": "boolean" }, "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "url": { "type": "string" }, "media": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } }, { "name": "get_product", "description": "Retrieve complete product detail by identifier. Returns a singular product\nwith a relevant set of variants, exact pricing, and real-time availability.\nSupports interactive option selection via selected and preferences parameters\nfor variant narrowing and availability signals. Use for product detail page\nrendering and purchase decisions.\n\nPrices in the response are integers in the currency's ISO 4217 minor units, paired with\na currency code: {\"amount\": 600, \"currency\": \"USD\"} is $6.00 and {\"amount\": 2500,\n\"currency\": \"USD\"} is $25.00. Convert to major units before quoting a price to a buyer\n(divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies\nsuch as JPY are already whole units).\n\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "catalog": { "type": "object", "description": "Product detail parameters.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Product ID." }, "selected": { "type": "array", "description": "Selected variant options.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" } } } }, "preferences": { "type": "array", "description": "Buyer preferences.", "items": { "type": "string" } }, "context": { "type": "object", "description": "Buyer signals for localization and personalization.", "additionalProperties": true, "properties": { "address_country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-2 format." }, "address_region": { "type": "string", "description": "Region or state." }, "postal_code": { "type": "string", "description": "Postal code." }, "language": { "type": "string", "description": "Language tag in IETF BCP 47 format." }, "currency": { "type": "string", "description": "Currency code in ISO 4217 format." }, "intent": { "type": "string", "description": "Buyer intent." } } }, "signals": { "type": "object", "description": "Platform environment data.", "additionalProperties": true, "properties": { "dev.ucp.buyer_ip": { "type": "string", "description": "Buyer IP address." }, "dev.ucp.user_agent": { "type": "string", "description": "Buyer user agent." } } }, "filters": { "type": "object", "description": "Narrowing criteria for catalog results.", "additionalProperties": true, "properties": { "categories": { "type": "array", "description": "Category filters combined with OR logic.", "items": { "type": "string" } }, "price": { "type": "object", "description": "Price range filter.", "properties": { "min": { "type": "integer", "description": "Minimum price in minor currency units." }, "max": { "type": "integer", "description": "Maximum price in minor currency units." } } }, "available": { "type": "boolean", "description": "Filter by availability. Default true (only sale-ready items).", "default": true } } } } } }, "required": [ "meta", "catalog" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Product detail response", "description": "One product with option availability and the effective selection.", "required": [ "ucp", "product" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Whether UCP processing succeeded." }, "services": { "type": "object", "description": "Services available to the agent.", "additionalProperties": true }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true }, "payment_handlers": { "type": "object", "description": "Payment handlers available to the buyer. Empty on receipts.", "additionalProperties": true } } }, "product": { "type": "object", "required": [ "id", "title", "description", "price_range", "variants" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "values" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "label" ], "additionalProperties": true, "properties": { "label": { "type": "string" }, "available": { "type": "boolean" }, "exists": { "type": "boolean" } } } } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "price" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "list_price": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "availability": { "type": "object", "additionalProperties": true, "properties": { "available": { "type": "boolean" } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "label" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "label": { "type": "string" } } } }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The media type, such as `image`." }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } }, "sku": { "type": "string" }, "requires": { "type": "object", "additionalProperties": true, "properties": { "shipping": { "type": "boolean" }, "selling_plan": { "type": "boolean" } } }, "checkout_url": { "type": "string", "description": "A cart permalink for the variant on this store." }, "selling_plans": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "group": { "type": "string" }, "recurring": { "type": "boolean" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "price": { "type": "object", "additionalProperties": true } } } } } } }, "url": { "type": "string", "description": "The online store URL." }, "handle": { "type": "string" }, "list_price_range": { "type": "object", "required": [ "min", "max" ], "additionalProperties": true, "properties": { "min": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } }, "max": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": true, "properties": { "amount": { "type": "integer", "description": "The amount in minor currency units." }, "currency": { "type": "string", "description": "The currency code (ISO 4217)." } } } } }, "categories": { "type": "array", "items": { "type": "object", "required": [ "value" ], "additionalProperties": true, "properties": { "value": { "type": "string" }, "taxonomy": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "selected": { "type": "array", "items": { "type": "object", "required": [ "name", "label" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "label": { "type": "string" } } } }, "gift_card": { "type": "boolean" }, "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "object", "additionalProperties": true, "properties": { "html": { "type": "string" } } }, "url": { "type": "string" }, "media": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "url": { "type": "string" }, "alt_text": { "type": "string" } } } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } }, { "name": "search_locations", "description": "Search this business's physical store locations.\n\nAn empty `location` object lists the stores. Narrow the list with a basic text `query`\n(every word must appear in the store name or address), and/or a `distance` relation: an explicit\n`center` latitude/longitude and an inclusive `max` radius in meters. With `distance`, results are\nordered nearest first (ties by location ID); otherwise they are in location ID order. Results are\npaginated; pass `pagination.cursor` from the response to fetch the next page.\n\n`filters.items` accepts up to ten unique nonempty Business-scoped item references, combined\nindependently with AND before pagination, not basket quantities. Overflow returns `invalid_input`,\nnever truncation. Exact visible variants only; unresolved or nonvariant items match nothing.\nAvailability uses Shopify's existing coarse policy and flag-dependent candidates, not shelf-stock,\npickup or reservation guarantees. Explicit `context.address_country` and `context.language` inform\nCatalog item resolution, never a distance center. Other context and signals remain ignored hints.\nHours, amenities, custom filters and any `serves` return `invalid_input` rather than being ignored.\n\nResponse uses the UCP location search shape (dev.ucp.common.location.search).\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "location": { "type": "object", "description": "Location search request. May be empty.", "properties": { "query": { "type": "string", "description": "Basic free-text match. Every whitespace-separated word must appear, case-insensitively, in the store name, street, city, region or postal code. Words match literally (no geocoding or abbreviations), so use full region names." }, "context": { "type": "object", "description": "Buyer context. Explicit address_country and language inform Catalog item resolution when items are filtered. Recognized country codes and names are normalized to alpha-2; language uses its uppercase primary tag (en-CA becomes EN). Unsupported evaluated country or language values return invalid_input. Valid values may use Catalog's shop fallback. Blank and other hints are ignored. Without items, context is ignored. Context never supplies a distance center and is not echoed.", "additionalProperties": true, "properties": { "address_country": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "location": { "type": "string" }, "intent": { "type": "string" }, "language": { "type": "string" }, "currency": { "type": "string" } } }, "signals": { "type": "object", "description": "Platform-observed environment signals. Accepted as hints only: never used to derive a location and not echoed.", "propertyNames": { "type": "string", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" }, "properties": { "dev.ucp.buyer_ip": { "type": "string" }, "dev.ucp.user_agent": { "type": "string" } }, "additionalProperties": true }, "distance": { "type": "object", "description": "Explicit-center radius using Shopify's spherical Haversine distance calculation. Matches locations whose distance from `center` is at most `max` meters. The center is never inferred from context, signals or the caller's IP, and the radius is never clamped. Locations without usable coordinates do not match.", "required": [ "center", "max" ], "properties": { "center": { "type": "object", "description": "WGS 84 coordinates in decimal degrees.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, "max": { "type": "number", "minimum": 0, "description": "Inclusive maximum distance in meters." } } }, "serves": { "type": "object", "description": "Serviceability targets are not supported by this business. Any value is rejected with invalid_input; use `distance` with an explicit center for proximity.", "additionalProperties": true }, "filters": { "type": "object", "description": "An empty object is accepted. Only items are supported; hours, amenities and custom filters are rejected with invalid_input instead of being ignored.", "properties": { "items": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Business-scoped item identifiers combined independently with AND, not basket quantities. At most ten raw references; overflow returns invalid_input, never truncation. Exact visible variants only; unknown or nonvariant items match nothing. Stock uses Shopify's coarse store availability and existing flag-dependent candidates, not shelf-stock, pickup or reservation guarantees." } }, "additionalProperties": true }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor from a previous response." }, "limit": { "type": "integer", "minimum": 1, "description": "Requested page size. The business may return fewer locations." } } } } } }, "required": [ "meta", "location" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Location search response or error", "description": "Locations matching the search. On a tool error, the error envelope.", "oneOf": [ { "type": "object", "title": "Location search response", "description": "Locations matching the search.", "required": [ "ucp", "locations" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success" ], "description": "Whether UCP processing succeeded." }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true } } }, "locations": { "type": "array", "items": { "type": "object", "description": "A physical store location.", "required": [ "id", "name" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Canonical Business location identifier." }, "name": { "type": "string", "description": "Buyer-facing location name." }, "address": { "type": "object", "description": "Public postal address and contact phone of the location.", "additionalProperties": true, "properties": { "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "address_country": { "type": "string" }, "postal_code": { "type": "string" }, "phone_number": { "type": "string" } } }, "geo": { "type": "object", "description": "WGS 84 coordinates of the location, in decimal degrees.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } } } } }, "pagination": { "type": "object", "description": "Cursor pagination for the next page of locations.", "required": [ "has_next_page" ], "properties": { "has_next_page": { "type": "boolean" }, "cursor": { "type": "string", "description": "Opaque cursor for the next page. Present when has_next_page is true." }, "total_count": { "type": "integer", "minimum": 0 } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type", "content" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } }, { "type": "object", "title": "Error response", "description": "The tool could not return its resource; `messages` explains why.", "required": [ "ucp", "messages" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "error" ] } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } ] } }, { "name": "lookup_locations", "description": "Look up this business's physical store locations by identifier.\n\nPass the canonical `id` values returned by search_locations in `ids`. Duplicate\nidentifiers are resolved once; each returned location lists the identifiers that\nresolved to it in `inputs`. Unknown identifiers are omitted from the result. Above the\nbusiness's batch limit only the first identifiers are processed and the response\ncarries a `batch_limit_applied` message.\n\nAn optional `distance` relation (explicit `center` and inclusive `max` meters) refines the\nresolved locations. `filters.items` accepts up to ten unique nonempty Business-scoped references,\ncombined independently with AND, not basket quantities. This budget is separate from the first-ten-\ndistinct-Location limit; item overflow returns `invalid_input`, never truncation. Exact visible\nvariants only; unresolved or nonvariant items match nothing. Availability uses Shopify's coarse\npolicy and existing flag-dependent candidates, not shelf-stock, pickup or reservation guarantees.\nExplicit `context.address_country` and `context.language` inform Catalog item resolution, never\na distance center. Other context and signals remain ignored hints. Hours, amenities, custom filters\nand any `serves` return `invalid_input` rather than being ignored.\n\nResponse uses the UCP location lookup shape (dev.ucp.common.location.lookup).\n", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meta": { "type": "object", "description": "Metadata for UCP agent profile discovery.", "properties": { "ucp-agent": { "type": "object", "properties": { "profile": { "type": "string", "format": "uri", "description": "Agent profile URI for UCP discovery." } }, "required": [ "profile" ] } }, "required": [ "ucp-agent" ] }, "location": { "type": "object", "description": "Location lookup request.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "Location identifiers to look up.", "items": { "type": "string" } }, "distance": { "type": "object", "description": "Explicit-center radius using Shopify's spherical Haversine distance calculation. Matches locations whose distance from `center` is at most `max` meters. The center is never inferred from context, signals or the caller's IP, and the radius is never clamped. Locations without usable coordinates do not match.", "required": [ "center", "max" ], "properties": { "center": { "type": "object", "description": "WGS 84 coordinates in decimal degrees.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, "max": { "type": "number", "minimum": 0, "description": "Inclusive maximum distance in meters." } } }, "serves": { "type": "object", "description": "Serviceability targets are not supported by this business. Any value is rejected with invalid_input; use `distance` with an explicit center for proximity.", "additionalProperties": true }, "filters": { "type": "object", "description": "An empty object is accepted. Only items are supported; hours, amenities and custom filters are rejected with invalid_input instead of being ignored.", "properties": { "items": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Business-scoped item identifiers combined independently with AND, not basket quantities. At most ten raw references; overflow returns invalid_input, never truncation. Exact visible variants only; unknown or nonvariant items match nothing. Stock uses Shopify's coarse store availability and existing flag-dependent candidates, not shelf-stock, pickup or reservation guarantees." } }, "additionalProperties": true }, "context": { "type": "object", "description": "Buyer context. Explicit address_country and language inform Catalog item resolution when items are filtered. Recognized country codes and names are normalized to alpha-2; language uses its uppercase primary tag (en-CA becomes EN). Unsupported evaluated country or language values return invalid_input. Valid values may use Catalog's shop fallback. Blank and other hints are ignored. Without items, context is ignored. Context never supplies a distance center and is not echoed.", "additionalProperties": true, "properties": { "address_country": { "type": "string" }, "address_region": { "type": "string" }, "postal_code": { "type": "string" }, "location": { "type": "string" }, "intent": { "type": "string" }, "language": { "type": "string" }, "currency": { "type": "string" } } }, "signals": { "type": "object", "description": "Platform-observed environment signals. Accepted as hints only: never used to derive a location and not echoed.", "propertyNames": { "type": "string", "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$" }, "properties": { "dev.ucp.buyer_ip": { "type": "string" }, "dev.ucp.user_agent": { "type": "string" } }, "additionalProperties": true } }, "required": [ "ids" ] } }, "required": [ "meta", "location" ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Location lookup response or error", "description": "Locations resolved from the requested identifiers. On a tool error, the error envelope.", "oneOf": [ { "type": "object", "title": "Location lookup response", "description": "Locations resolved from the requested identifiers.", "required": [ "ucp", "locations" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "description": "UCP protocol metadata for the response.", "required": [ "version" ], "additionalProperties": true, "properties": { "version": { "type": "string", "description": "The negotiated UCP version." }, "status": { "type": "string", "enum": [ "success" ], "description": "Whether UCP processing succeeded." }, "capabilities": { "type": "object", "description": "Negotiated UCP capabilities.", "additionalProperties": true } } }, "locations": { "type": "array", "items": { "type": "object", "description": "A physical store location and the request identifiers that resolved to it.", "required": [ "id", "name", "inputs" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Canonical Business location identifier." }, "name": { "type": "string", "description": "Buyer-facing location name." }, "address": { "type": "object", "description": "Public postal address and contact phone of the location.", "additionalProperties": true, "properties": { "street_address": { "type": "string" }, "extended_address": { "type": "string" }, "address_locality": { "type": "string" }, "address_region": { "type": "string" }, "address_country": { "type": "string" }, "postal_code": { "type": "string" }, "phone_number": { "type": "string" } } }, "geo": { "type": "object", "description": "WGS 84 coordinates of the location, in decimal degrees.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, "inputs": { "type": "array", "description": "The request identifiers, exactly as supplied, that resolved to this location.", "minItems": 1, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type", "content" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } }, { "type": "object", "title": "Error response", "description": "The tool could not return its resource; `messages` explains why.", "required": [ "ucp", "messages" ], "additionalProperties": true, "properties": { "ucp": { "type": "object", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "error" ] } } }, "messages": { "type": "array", "description": "Errors or warnings surfaced while processing the tool call.", "items": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "error", "warning", "info" ] }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "code": { "type": "string" }, "content": { "type": "string" }, "severity": { "type": "string", "enum": [ "recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable" ] }, "path": { "type": "string" } } } } } } ] } } ] } }