Search and shop Diana Rafael natural black diamond fine jewelry: catalog, products, cart, checkout.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Cancels a cart. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
The ID of the cart. Format: 'gid://shopify/Cart/abc123'
Metadata for UCP agent profile discovery.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Cancels a cart. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the cart. Format: 'gid://shopify/Cart/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Cancels a checkout. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}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. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
| checkout* | object | Checkout properties. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id",
"checkout"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent",
"idempotency-key"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
},
"idempotency-key": {
"type": "string",
"description": "An idempotency key for completing the checkout."
}
},
"description": "Metadata for UCP agent profile discovery."
},
"checkout": {
"type": "object",
"required": [
"payment"
],
"properties": {
"buyer": {
"type": "object",
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"payment": {
"type": "object",
"properties": {
"instruments": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"handler_id"
],
"properties": {
"handler_id": {
"const": "apple-pay"
}
}
},
"else": {
"properties": {
"credential": {
"required": [
"type"
],
"properties": {
"type": {
"not": {
"const": "apple_pay_token"
}
}
}
}
}
},
"then": {
"required": [
"billing_address",
"credential"
],
"properties": {
"type": {
"const": "card"
},
"credential": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
}
}
}
}
],
"required": [
"id",
"handler_id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for this payment instrument instance."
},
"type": {
"type": "string",
"description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card."
},
"display": {
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Card brand (e.g., visa, mastercard), when available."
},
"expiry_year": {
"type": "integer",
"description": "Card expiry year. Required for card instruments."
},
"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."
},
"rich_card_art": {
"type": "string",
"description": "Rich card art URL or identifier for the payment instrument."
},
"funding_source": {
"enum": [
"debit",
"credit",
"prepaid",
"store"
],
"type": "string",
"description": "How the card is funded, as reported by Apple Pay."
},
"rich_text_description": {
"type": "string",
"description": "Rich text description of the payment instrument for display purposes."
}
},
"description": "Display information for this payment instrument.",
"additionalProperties": true
},
"selected": {
"type": "boolean",
"description": "Whether this instrument is the currently selected for the checkout."
},
"credential": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
},
"else": {
"required": [
"type"
]
},
"then": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
},
"payment_data": {
"type": "object",
"required": [
"version",
"data",
"signature",
"header"
],
"properties": {
"data": {
"type": "string"
},
"header": {
"type": "object",
"anyOf": [
{
"required": [
"ephemeral_public_key"
]
},
{
"required": [
"wrapped_key"
]
}
],
"required": [
"public_key_hash",
"transaction_id"
],
"properties": {
"wrapped_key": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"public_key_hash": {
"type": "string"
},
"application_data": {
"type": "string"
},
"ephemeral_public_key": {
"type": "string"
}
},
"additionalProperties": true
},
"version": {
"type": "string"
},
"signature": {
"type": "string"
}
},
"additionalProperties": true
},
"transaction_identifier": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)."
},
"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."
},
"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."
},
"payment_data": {
"type": "object"
},
"transaction_identifier": {
"type": "string"
}
},
"description": "Payment credential payload to process the transaction for this instrument.",
"additionalProperties": true
},
"handler_id": {
"type": "string",
"description": "Identifier of the payment handler that was used to generate this instrument."
},
"billing_address": {
"type": "object",
"properties": {
"last_name": {
"type": "string",
"description": "Last name of the contact associated with the billing address."
},
"first_name": {
"type": "string",
"description": "First name of the contact associated with the billing address."
},
"postal_code": {
"type": "string",
"description": "Postal code of the billing address."
},
"phone_number": {
"type": "string",
"description": "Phone number of the contact associated with the billing address."
},
"address_region": {
"type": "string",
"description": "Region of the billing address."
},
"street_address": {
"type": "string",
"description": "Street address of the billing address."
},
"address_country": {
"type": "string",
"description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format."
},
"address_locality": {
"type": "string",
"description": "Locality 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."
}
},
"description": "Billing address for the instrument.",
"additionalProperties": true
}
},
"additionalProperties": true
},
"description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets)."
}
},
"description": "Payment information for this checkout.",
"additionalProperties": true
},
"attribution": {
"type": "object",
"properties": {
"utm_term": {
"type": "string",
"description": "UTM term parameter."
},
"utm_medium": {
"type": "string",
"description": "UTM medium parameter."
},
"utm_source": {
"type": "string",
"description": "UTM source parameter."
},
"utm_content": {
"type": "string",
"description": "UTM content parameter."
},
"click_id_tag": {
"type": "string",
"description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')."
},
"utm_campaign": {
"type": "string",
"description": "UTM campaign parameter."
},
"click_id_value": {
"type": "string",
"description": "Click identifier value matching click_id_tag."
},
"activity_id_tag": {
"type": "string",
"description": "Activity identifier parameter name."
},
"referring_domain": {
"type": "string",
"description": "Domain that referred the buyer to the merchant's storefront."
},
"activity_id_value": {
"type": "string",
"description": "Activity identifier value matching activity_id_tag."
}
},
"description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters)."
}
},
"description": "Checkout properties."
}
}
}Creates a new cart Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| cart* | object | Cart properties. |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"cart"
],
"properties": {
"cart": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"buyer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"phone_number": {
"type": "string"
}
},
"description": "Information about the buyer including email and phone number.",
"additionalProperties": true
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Context describing buyer's intent."
},
"currency": {
"type": "string",
"description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"eligibility": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty')."
},
"description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar."
},
"postal_code": {
"type": "string",
"description": "Postal code hint for localization."
},
"address_region": {
"type": "string",
"description": "Region/state hint for localization."
},
"address_country": {
"type": "string",
"description": "Country hint for localization."
}
},
"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
},
"discounts": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear."
}
},
"description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the line item to update."
},
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The Product Variant ID to add or update."
}
}
},
"quantity": {
"type": "integer"
}
}
},
"description": "Items to add to the cart or checkout. Required when creating a new cart or checkout."
},
"attribution": {
"type": "object",
"properties": {
"utm_term": {
"type": "string",
"description": "UTM term parameter."
},
"utm_medium": {
"type": "string",
"description": "UTM medium parameter."
},
"utm_source": {
"type": "string",
"description": "UTM source parameter."
},
"utm_content": {
"type": "string",
"description": "UTM content parameter."
},
"click_id_tag": {
"type": "string",
"description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')."
},
"utm_campaign": {
"type": "string",
"description": "UTM campaign parameter."
},
"click_id_value": {
"type": "string",
"description": "Click identifier value matching click_id_tag."
},
"activity_id_tag": {
"type": "string",
"description": "Activity identifier parameter name."
},
"referring_domain": {
"type": "string",
"description": "Domain that referred the buyer to the merchant's storefront."
},
"activity_id_value": {
"type": "string",
"description": "Activity identifier value matching activity_id_tag."
}
},
"description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters). Forwarded to the cart for downstream reporting."
},
"fulfillment": {
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"selected_option_id": {
"type": "string"
}
}
},
"description": "The groups to fulfill to."
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"address_region": {
"type": "string"
},
"street_address": {
"type": "string"
},
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"extended_address": {
"type": "string"
}
}
},
"description": "The destinations to fulfill to."
},
"selected_destination_id": {
"type": "string",
"description": "ID of the selected destination."
}
}
},
"description": "The methods of fulfillment."
}
},
"description": "Information about the fulfillment."
}
},
"description": "Cart properties."
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Creates a checkout. Returns checkout details, including line items, totals, and any applicable discounts or taxes. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| meta* | object | Metadata for UCP agent profile discovery. |
| checkout* | object | Checkout properties. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"checkout"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
},
"checkout": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"buyer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"phone_number": {
"type": "string"
}
},
"description": "Information about the buyer including email and phone number.",
"additionalProperties": true
},
"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'"
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Context describing buyer's intent."
},
"currency": {
"type": "string",
"description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"eligibility": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty')."
},
"description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar."
},
"postal_code": {
"type": "string",
"description": "Postal code hint for localization."
},
"address_region": {
"type": "string",
"description": "Region/state hint for localization."
},
"address_country": {
"type": "string",
"description": "Country hint for localization."
}
},
"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
},
"payment": {
"type": "object",
"properties": {
"instruments": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"handler_id"
],
"properties": {
"handler_id": {
"const": "apple-pay"
}
}
},
"else": {
"properties": {
"credential": {
"required": [
"type"
],
"properties": {
"type": {
"not": {
"const": "apple_pay_token"
}
}
}
}
}
},
"then": {
"required": [
"billing_address",
"credential"
],
"properties": {
"type": {
"const": "card"
},
"credential": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
}
}
}
}
],
"required": [
"id",
"handler_id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for this payment instrument instance."
},
"type": {
"type": "string",
"description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card."
},
"display": {
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Card brand (e.g., visa, mastercard), when available."
},
"expiry_year": {
"type": "integer",
"description": "Card expiry year. Required for card instruments."
},
"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."
},
"rich_card_art": {
"type": "string",
"description": "Rich card art URL or identifier for the payment instrument."
},
"funding_source": {
"enum": [
"debit",
"credit",
"prepaid",
"store"
],
"type": "string",
"description": "How the card is funded, as reported by Apple Pay."
},
"rich_text_description": {
"type": "string",
"description": "Rich text description of the payment instrument for display purposes."
}
},
"description": "Display information for this payment instrument.",
"additionalProperties": true
},
"selected": {
"type": "boolean",
"description": "Whether this instrument is the currently selected for the checkout."
},
"credential": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
},
"else": {
"required": [
"type"
]
},
"then": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
},
"payment_data": {
"type": "object",
"required": [
"version",
"data",
"signature",
"header"
],
"properties": {
"data": {
"type": "string"
},
"header": {
"type": "object",
"anyOf": [
{
"required": [
"ephemeral_public_key"
]
},
{
"required": [
"wrapped_key"
]
}
],
"required": [
"public_key_hash",
"transaction_id"
],
"properties": {
"wrapped_key": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"public_key_hash": {
"type": "string"
},
"application_data": {
"type": "string"
},
"ephemeral_public_key": {
"type": "string"
}
},
"additionalProperties": true
},
"version": {
"type": "string"
},
"signature": {
"type": "string"
}
},
"additionalProperties": true
},
"transaction_identifier": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)."
},
"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."
},
"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."
},
"payment_data": {
"type": "object"
},
"transaction_identifier": {
"type": "string"
}
},
"description": "Payment credential payload to process the transaction for this instrument.",
"additionalProperties": true
},
"handler_id": {
"type": "string",
"description": "Identifier of the payment handler that was used to generate this instrument."
},
"billing_address": {
"type": "object",
"properties": {
"last_name": {
"type": "string",
"description": "Last name of the contact associated with the billing address."
},
"first_name": {
"type": "string",
"description": "First name of the contact associated with the billing address."
},
"postal_code": {
"type": "string",
"description": "Postal code of the billing address."
},
"phone_number": {
"type": "string",
"description": "Phone number of the contact associated with the billing address."
},
"address_region": {
"type": "string",
"description": "Region of the billing address."
},
"street_address": {
"type": "string",
"description": "Street address of the billing address."
},
"address_country": {
"type": "string",
"description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format."
},
"address_locality": {
"type": "string",
"description": "Locality 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."
}
},
"description": "Billing address for the instrument.",
"additionalProperties": true
}
},
"additionalProperties": true
},
"description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets)."
}
},
"description": "Payment information for this checkout.",
"additionalProperties": true
},
"discounts": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear."
}
},
"description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the line item to update."
},
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The Product Variant ID to add or update."
}
}
},
"quantity": {
"type": "integer"
}
}
},
"description": "Items to add to the cart or checkout. Required when creating a new cart or checkout."
},
"attribution": {
"type": "object",
"properties": {
"utm_term": {
"type": "string",
"description": "UTM term parameter."
},
"utm_medium": {
"type": "string",
"description": "UTM medium parameter."
},
"utm_source": {
"type": "string",
"description": "UTM source parameter."
},
"utm_content": {
"type": "string",
"description": "UTM content parameter."
},
"click_id_tag": {
"type": "string",
"description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')."
},
"utm_campaign": {
"type": "string",
"description": "UTM campaign parameter."
},
"click_id_value": {
"type": "string",
"description": "Click identifier value matching click_id_tag."
},
"activity_id_tag": {
"type": "string",
"description": "Activity identifier parameter name."
},
"referring_domain": {
"type": "string",
"description": "Domain that referred the buyer to the merchant's storefront."
},
"activity_id_value": {
"type": "string",
"description": "Activity identifier value matching activity_id_tag."
}
},
"description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters)."
},
"fulfillment": {
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"selected_option_id": {
"type": "string"
}
}
},
"description": "The groups to fulfill to."
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"address_region": {
"type": "string"
},
"street_address": {
"type": "string"
},
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"extended_address": {
"type": "string"
}
}
},
"description": "The destinations to fulfill to."
},
"selected_destination_id": {
"type": "string",
"description": "ID of the selected destination."
}
}
},
"description": "The methods of fulfillment."
}
},
"description": "Information about the fulfillment."
}
},
"description": "Checkout properties."
}
}
}Get the cart contents Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the cart. Format: 'gid://shopify/Cart/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Returns details about the checkout, including line items, totals, and any applicable discounts or taxes. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Get the details of an order Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the order. Format: 'gid://shopify/Order/123' |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the order. Format: 'gid://shopify/Order/123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Retrieve complete product detail by identifier. Returns a singular product with a relevant set of variants, exact pricing, and real-time availability. Supports interactive option selection via selected and preferences parameters for variant narrowing and availability signals. Use for product detail page rendering and purchase decisions. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| meta* | object | Metadata for UCP agent profile discovery. |
| catalog* | object | Product detail parameters. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"catalog"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
},
"catalog": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Product ID."
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Buyer intent."
},
"currency": {
"type": "string",
"description": "Currency code in ISO 4217 format."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"postal_code": {
"type": "string",
"description": "Postal code."
},
"address_region": {
"type": "string",
"description": "Region or state."
},
"address_country": {
"type": "string",
"description": "Country code in ISO 3166-1 alpha-2 format."
}
},
"description": "Buyer signals for localization and personalization.",
"additionalProperties": true
},
"filters": {
"type": "object",
"properties": {
"price": {
"type": "object",
"properties": {
"max": {
"type": "integer",
"description": "Maximum price in minor currency units."
},
"min": {
"type": "integer",
"description": "Minimum price in minor currency units."
}
},
"description": "Price range filter."
},
"available": {
"type": "boolean",
"default": true,
"description": "Filter by availability. Default true (only sale-ready items)."
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Category filters combined with OR logic."
}
},
"description": "Narrowing criteria for catalog results.",
"additionalProperties": true
},
"signals": {
"type": "object",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string",
"description": "Buyer IP address."
},
"dev.ucp.user_agent": {
"type": "string",
"description": "Buyer user agent."
}
},
"description": "Platform environment data.",
"additionalProperties": true
},
"selected": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"label": {
"type": "string"
}
}
},
"description": "Selected variant options."
},
"preferences": {
"type": "array",
"items": {
"type": "string"
},
"description": "Buyer preferences."
}
},
"description": "Product detail parameters."
}
}
}Look up multiple products or variants by identifier. Use this tool to resolve multiple product/variant IDs in a single request. Supports: - Product IDs (gid://shopify/Product/...): Returns product with match: "featured" - Variant IDs (gid://shopify/ProductVariant/...): Returns parent product with the exact variant Results are grouped by product. Each variant includes an inputs array showing which request ID resolved to it and whether the match was exact or featured. In versions that require input correlations, only matched variants are returned. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units). Maximum 10 IDs per request.
| Argument | Type | Description |
|---|---|---|
| meta* | object | Metadata for UCP agent profile discovery. |
| catalog* | object | Catalog lookup parameters. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"catalog"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
},
"catalog": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"minItems": 1,
"description": "Product IDs to look up."
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Buyer intent."
},
"currency": {
"type": "string",
"description": "Currency code in ISO 4217 format."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"postal_code": {
"type": "string",
"description": "Postal code."
},
"address_region": {
"type": "string",
"description": "Region or state."
},
"address_country": {
"type": "string",
"description": "Country code in ISO 3166-1 alpha-2 format."
}
},
"description": "Buyer signals for localization and personalization.",
"additionalProperties": true
},
"filters": {
"type": "object",
"properties": {
"price": {
"type": "object",
"properties": {
"max": {
"type": "integer",
"description": "Maximum price in minor currency units."
},
"min": {
"type": "integer",
"description": "Minimum price in minor currency units."
}
},
"description": "Price range filter."
},
"available": {
"type": "boolean",
"default": true,
"description": "Filter by availability. Default true (only sale-ready items)."
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Category filters combined with OR logic."
}
},
"description": "Narrowing criteria for catalog results.",
"additionalProperties": true
},
"signals": {
"type": "object",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string",
"description": "Buyer IP address."
},
"dev.ucp.user_agent": {
"type": "string",
"description": "Buyer user agent."
}
},
"description": "Platform environment data.",
"additionalProperties": true
}
},
"description": "Catalog lookup parameters."
}
}
}Search for products from the online store, hosted on Shopify. This tool can be used to search for products using natural language queries, specific filter criteria, or both. At least one of query or filters must be provided. Results are paginated, with initial results limited to improve experience. Use the pagination.cursor from the response to fetch additional pages when users request more results. Response conforms to the UCP catalog search capability (dev.ucp.shopping.catalog.search). Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| meta* | object | Metadata for UCP agent profile discovery. |
| catalog* | object | Catalog search parameters. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"catalog"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
},
"catalog": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query string."
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Buyer intent."
},
"currency": {
"type": "string",
"description": "Currency code in ISO 4217 format."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"postal_code": {
"type": "string",
"description": "Postal code."
},
"address_region": {
"type": "string",
"description": "Region or state."
},
"address_country": {
"type": "string",
"description": "Country code in ISO 3166-1 alpha-2 format."
}
},
"description": "Buyer signals for localization and personalization.",
"additionalProperties": true
},
"filters": {
"type": "object",
"properties": {
"price": {
"type": "object",
"properties": {
"max": {
"type": "integer",
"description": "Maximum price in minor currency units."
},
"min": {
"type": "integer",
"description": "Minimum price in minor currency units."
}
},
"description": "Price range filter."
},
"available": {
"type": "boolean",
"default": true,
"description": "Filter by availability. Default true (only sale-ready items)."
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Category filters combined with OR logic."
}
},
"description": "Narrowing criteria for catalog results.",
"additionalProperties": true
},
"signals": {
"type": "object",
"properties": {
"dev.ucp.buyer_ip": {
"type": "string",
"description": "Buyer IP address."
},
"dev.ucp.user_agent": {
"type": "string",
"description": "Buyer user agent."
}
},
"description": "Platform environment data.",
"additionalProperties": true
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 10,
"minimum": 1,
"description": "Number of results to return."
},
"cursor": {
"type": "string",
"description": "Pagination cursor."
}
},
"description": "Pagination parameters."
}
},
"description": "Catalog search parameters."
}
}
}Perform updates to a cart. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the cart. Format: 'gid://shopify/Cart/abc123' |
| cart* | object | Cart properties. |
| meta* | object | Metadata for UCP agent profile discovery. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"cart",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the cart. Format: 'gid://shopify/Cart/abc123'"
},
"cart": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"buyer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"phone_number": {
"type": "string"
}
},
"description": "Information about the buyer including email and phone number.",
"additionalProperties": true
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Context describing buyer's intent."
},
"currency": {
"type": "string",
"description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"eligibility": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty')."
},
"description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar."
},
"postal_code": {
"type": "string",
"description": "Postal code hint for localization."
},
"address_region": {
"type": "string",
"description": "Region/state hint for localization."
},
"address_country": {
"type": "string",
"description": "Country hint for localization."
}
},
"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
},
"discounts": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear."
}
},
"description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the line item to update."
},
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The Product Variant ID to add or update."
}
}
},
"quantity": {
"type": "integer"
}
}
},
"description": "Items to add to the cart or checkout. Required when creating a new cart or checkout."
},
"attribution": {
"type": "object",
"properties": {
"utm_term": {
"type": "string",
"description": "UTM term parameter."
},
"utm_medium": {
"type": "string",
"description": "UTM medium parameter."
},
"utm_source": {
"type": "string",
"description": "UTM source parameter."
},
"utm_content": {
"type": "string",
"description": "UTM content parameter."
},
"click_id_tag": {
"type": "string",
"description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')."
},
"utm_campaign": {
"type": "string",
"description": "UTM campaign parameter."
},
"click_id_value": {
"type": "string",
"description": "Click identifier value matching click_id_tag."
},
"activity_id_tag": {
"type": "string",
"description": "Activity identifier parameter name."
},
"referring_domain": {
"type": "string",
"description": "Domain that referred the buyer to the merchant's storefront."
},
"activity_id_value": {
"type": "string",
"description": "Activity identifier value matching activity_id_tag."
}
},
"description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters). Forwarded to the cart for downstream reporting."
},
"fulfillment": {
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "object",
"required": [
"line_item_ids"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"selected_option_id": {
"type": "string"
}
}
},
"description": "The groups to fulfill to."
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"address_region": {
"type": "string"
},
"street_address": {
"type": "string"
},
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"extended_address": {
"type": "string"
}
}
},
"description": "The destinations to fulfill to."
},
"line_item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The line item ids to fulfill."
},
"selected_destination_id": {
"type": "string",
"description": "ID of the selected destination."
}
}
},
"description": "The methods of fulfillment."
}
},
"description": "Information about the fulfillment."
}
},
"description": "Cart properties."
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
}
}
}Updates a checkout. Returns checkout details, including line items, totals, and any applicable discounts or taxes. Prices in the response are integers in the currency's ISO 4217 minor units, paired with a currency code: {"amount": 600, "currency": "USD"} is $6.00 and {"amount": 2500, "currency": "USD"} is $25.00. Convert to major units before quoting a price to a buyer (divide by 100 for two-decimal currencies such as USD and EUR; zero-decimal currencies such as JPY are already whole units).
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123' |
| meta* | object | Metadata for UCP agent profile discovery. |
| checkout* | object | Checkout properties. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"meta",
"checkout",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"description": "Agent profile URI for UCP discovery."
}
}
}
},
"description": "Metadata for UCP agent profile discovery."
},
"checkout": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"buyer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
},
"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"
],
"properties": {
"source": {
"enum": [
"business",
"platform"
],
"type": "string",
"description": "Use platform for an explicit buyer decision. Business-sourced values do not update stored choices."
},
"granted": {
"type": "boolean",
"description": "Whether consent is granted."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"phone_number": {
"type": "string"
}
},
"description": "Information about the buyer including email and phone number.",
"additionalProperties": true
},
"context": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Context describing buyer's intent."
},
"currency": {
"type": "string",
"description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD')."
},
"language": {
"type": "string",
"description": "Language tag in IETF BCP 47 format."
},
"eligibility": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
"description": "Reverse-domain identifier. Must contain at least two dot-separated segments (e.g., 'com.example.loyalty')."
},
"description": "Buyer claims about eligible benefits such as loyalty membership, payment perks, and similar."
},
"postal_code": {
"type": "string",
"description": "Postal code hint for localization."
},
"address_region": {
"type": "string",
"description": "Region/state hint for localization."
},
"address_country": {
"type": "string",
"description": "Country hint for localization."
}
},
"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
},
"payment": {
"type": "object",
"properties": {
"instruments": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"handler_id"
],
"properties": {
"handler_id": {
"const": "apple-pay"
}
}
},
"else": {
"properties": {
"credential": {
"required": [
"type"
],
"properties": {
"type": {
"not": {
"const": "apple_pay_token"
}
}
}
}
}
},
"then": {
"required": [
"billing_address",
"credential"
],
"properties": {
"type": {
"const": "card"
},
"credential": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
}
}
}
}
],
"required": [
"id",
"handler_id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for this payment instrument instance."
},
"type": {
"type": "string",
"description": "Instrument type. Apple Pay uses 'card' because the submitted instrument represents a tokenized card."
},
"display": {
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Card brand (e.g., visa, mastercard), when available."
},
"expiry_year": {
"type": "integer",
"description": "Card expiry year. Required for card instruments."
},
"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."
},
"rich_card_art": {
"type": "string",
"description": "Rich card art URL or identifier for the payment instrument."
},
"funding_source": {
"enum": [
"debit",
"credit",
"prepaid",
"store"
],
"type": "string",
"description": "How the card is funded, as reported by Apple Pay."
},
"rich_text_description": {
"type": "string",
"description": "Rich text description of the payment instrument for display purposes."
}
},
"description": "Display information for this payment instrument.",
"additionalProperties": true
},
"selected": {
"type": "boolean",
"description": "Whether this instrument is the currently selected for the checkout."
},
"credential": {
"type": "object",
"allOf": [
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "apple_pay_token"
}
}
},
"else": {
"required": [
"type"
]
},
"then": {
"required": [
"type",
"payment_data"
],
"properties": {
"type": {
"const": "apple_pay_token"
},
"payment_data": {
"type": "object",
"required": [
"version",
"data",
"signature",
"header"
],
"properties": {
"data": {
"type": "string"
},
"header": {
"type": "object",
"anyOf": [
{
"required": [
"ephemeral_public_key"
]
},
{
"required": [
"wrapped_key"
]
}
],
"required": [
"public_key_hash",
"transaction_id"
],
"properties": {
"wrapped_key": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"public_key_hash": {
"type": "string"
},
"application_data": {
"type": "string"
},
"ephemeral_public_key": {
"type": "string"
}
},
"additionalProperties": true
},
"version": {
"type": "string"
},
"signature": {
"type": "string"
}
},
"additionalProperties": true
},
"transaction_identifier": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"description": "Namespaced token type using dot notation (e.g., stripe.token, merchant.token, google.pay)."
},
"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."
},
"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."
},
"payment_data": {
"type": "object"
},
"transaction_identifier": {
"type": "string"
}
},
"description": "Payment credential payload to process the transaction for this instrument.",
"additionalProperties": true
},
"handler_id": {
"type": "string",
"description": "Identifier of the payment handler that was used to generate this instrument."
},
"billing_address": {
"type": "object",
"properties": {
"last_name": {
"type": "string",
"description": "Last name of the contact associated with the billing address."
},
"first_name": {
"type": "string",
"description": "First name of the contact associated with the billing address."
},
"postal_code": {
"type": "string",
"description": "Postal code of the billing address."
},
"phone_number": {
"type": "string",
"description": "Phone number of the contact associated with the billing address."
},
"address_region": {
"type": "string",
"description": "Region of the billing address."
},
"street_address": {
"type": "string",
"description": "Street address of the billing address."
},
"address_country": {
"type": "string",
"description": "Country of the billing address in 2-letter ISO 3166-1 alpha-2 format."
},
"address_locality": {
"type": "string",
"description": "Locality 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."
}
},
"description": "Billing address for the instrument.",
"additionalProperties": true
}
},
"additionalProperties": true
},
"description": "Payment instruments for this checkout (e.g., credit cards, tokens, wallets)."
}
},
"description": "Payment information for this checkout.",
"additionalProperties": true
},
"discounts": {
"type": "object",
"properties": {
"codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear."
}
},
"description": "Discount or promo codes to apply to the cart. Only prompt if customer mentions having a discount code."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the line item to update."
},
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The Product Variant ID to add or update."
}
}
},
"quantity": {
"type": "integer"
}
}
},
"description": "Items to add to the cart or checkout. Required when creating a new cart or checkout."
},
"attribution": {
"type": "object",
"properties": {
"utm_term": {
"type": "string",
"description": "UTM term parameter."
},
"utm_medium": {
"type": "string",
"description": "UTM medium parameter."
},
"utm_source": {
"type": "string",
"description": "UTM source parameter."
},
"utm_content": {
"type": "string",
"description": "UTM content parameter."
},
"click_id_tag": {
"type": "string",
"description": "Click identifier parameter name (e.g., 'gclid', 'fbclid')."
},
"utm_campaign": {
"type": "string",
"description": "UTM campaign parameter."
},
"click_id_value": {
"type": "string",
"description": "Click identifier value matching click_id_tag."
},
"activity_id_tag": {
"type": "string",
"description": "Activity identifier parameter name."
},
"referring_domain": {
"type": "string",
"description": "Domain that referred the buyer to the merchant's storefront."
},
"activity_id_value": {
"type": "string",
"description": "Activity identifier value matching activity_id_tag."
}
},
"description": "Marketing attribution context for the buyer's session (referring domain, click IDs, UTM parameters)."
},
"fulfillment": {
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "object",
"required": [
"line_item_ids"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"selected_option_id": {
"type": "string"
}
}
},
"description": "The groups to fulfill to."
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"address_region": {
"type": "string"
},
"street_address": {
"type": "string"
},
"address_country": {
"type": "string"
},
"address_locality": {
"type": "string"
},
"extended_address": {
"type": "string"
}
}
},
"description": "The destinations to fulfill to."
},
"line_item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The line item ids to fulfill."
},
"selected_destination_id": {
"type": "string",
"description": "ID of the selected destination."
}
}
},
"description": "The methods of fulfillment."
}
},
"description": "Information about the fulfillment."
}
},
"description": "Checkout properties."
}
}
}