Input schema (JSON)
{
"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."
}
}
}