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).
View input 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"
}
}
}
},
"declared_fields": {
"type": "array",
"description": "Merchant-defined cart or checkout fields and their values. On updates, replaces previously submitted custom field values; omitted or null fields are cleared. Send empty array to clear all custom fields.",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"description": "Unique identifier for the declared field."
},
"value": {
"type": [
"string",
"number",
"boolean",
"object",
"array",
"null"
],
"description": "Submitted JSON value for the field. Null clears the value."
}
}
}
}
},
"required": [
"line_items"
]
},
"id": {
"type": "string",
"description": "The ID of the checkout to update. Format: 'gid://shopify/Checkout/abc123'"
}
},
"required": [
"meta",
"checkout",
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}