Skip to content

Schema Reference

This page provides a reference for all the capability data models and types used within the UCP.

Capability Schemas

Cart

Name Type Required Description
ucp Ucp Response Cart Schema Yes Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
id string Yes Unique cart identifier.
line_items Array[Line Item] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
buyer Buyer No Optional buyer information for personalized estimates.
currency string Yes ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals Array[Total] Yes Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages Array[Message] No Validation messages, warnings, or informational notices.
links Array[Link] No Optional merchant links (policies, FAQs).
continue_url string No URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at string No Cart expiry timestamp (RFC 3339). Optional.

Catalog Lookup

Product/variant lookup by identifier capability.

Product catalog search capability.

Checkout

Name Type Required Description
ucp Ucp Response Checkout Schema Yes Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
id string Yes Unique identifier of the checkout session.
line_items Array[Line Item] Yes List of line items being checked out.
buyer Buyer No Representation of the buyer.
context Context No Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
status string Yes Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.
Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency string Yes ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals Array[Total] Yes Different cart totals.
messages Array[Message] No List of messages with error and info about the checkout session state.
links Array[Link] Yes Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at string No RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url string No URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment Payment No Payment configuration containing handlers.
order Order Confirmation No Details about an order created for this checkout session.

Order

Name Type Required Description
ucp Ucp Response Order Schema Yes Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
id string Yes Unique order identifier.
checkout_id string Yes Associated checkout ID for reconciliation.
permalink_url string Yes Permalink to access the order on merchant site.
line_items Array[Order Line Item] Yes Immutable line items — source of truth for what was ordered.
fulfillment object Yes Fulfillment data: buyer expectations and what actually happened.
adjustments Array[Adjustment] No Append-only event log of money movements (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment.
currency string No ISO 4217 currency code. MUST match the currency from the originating checkout session.
totals Array[Total] Yes Different totals for the order.

Payment

Name Type Required Description
instruments Array[Payment Instrument Selected Payment Instrument] No The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields.

Type Schemas

Payment Account Info

Name Type Required Description
payment_account_reference string No EMVCo PAR. A unique identifier linking a payment card to a specific account, enabling tracking across tokens (Apple Pay, physical card, etc).

Adjustment

Name Type Required Description
id string Yes Adjustment event identifier.
type string Yes Type of adjustment (open string). Typically money-related like: refund, return, credit, price_adjustment, dispute, cancellation. Can be any value that makes sense for the merchant's business.
occurred_at string Yes RFC 3339 timestamp when this adjustment occurred.
status string Yes Adjustment status.
Enum: pending, completed, failed
line_items Array[object] No Which line items and quantities are affected (optional).
amount Amount No Amount in ISO 4217 minor units for refunds, credits, or price adjustments.
description string No Human-readable reason or description (e.g., 'Defective item', 'Customer requested').

Amount

Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD).

Available Payment Instrument

Name Type Required Description
type string Yes The instrument type identifier (e.g., 'card', 'gift_card'). References an instrument schema's type constant.
constraints object No Constraints on this instrument type. Structure depends on instrument type and active capabilities.

Binding

Name Type Required Description
checkout_id string Yes The checkout session identifier this token is bound to.
identity Payment Identity No The participant this token is bound to. Required when acting on behalf of another participant (e.g., agent tokenizing for merchant). Omit when the authenticated caller is the binding target.

Business Fulfillment Config

Name Type Required Description
allows_multi_destination object No Permits multiple destinations per method type.
allows_method_combinations Array[array] No Allowed method type combinations.

Buyer

Name Type Required Description
first_name string No First name of the buyer.
last_name string No Last name of the buyer.
email string No Email of the buyer.
phone_number string No E.164 standard.

Card Credential

Name Type Required Description
type string Yes The credential type discriminator. Specific schemas will constrain this to a constant value.
type any Yes Constant = card. The credential type identifier for card credentials.
card_number_type string Yes The type of card number. Network tokens are preferred with fallback to FPAN. See PCI Scope for more details.
Enum: fpan, network_token, dpan
number string No Card number.
expiry_month integer No The month of the card's expiration date (1-12).
expiry_year integer No The year of the card's expiration date.
name string No Cardholder name.
cvc string No Card CVC number.
cryptogram string No Cryptogram provided with network tokens.
eci_value string No Electronic Commerce Indicator / Security Level Indicator provided with network tokens.

Card Payment Instrument

Name Type Required Description
id string Yes A unique identifier for this instrument instance, assigned by the platform.
handler_id string Yes The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition.
type string Yes The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value.
billing_address Postal Address No The billing address associated with this payment method.
credential Payment Credential No The base definition for any payment credential. Handlers define specific credential types.
display object No Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.
type string Yes Constant = card. Indicates this is a card payment instrument.
display object No Display information for this card payment instrument.

Category

Name Type Required Description
value string Yes Category value or path (e.g., 'Apparel > Shirts', '1604').
taxonomy string No Source taxonomy. Well-known values: google_product_category, shopify, merchant.

Context

Name Type Required Description
address_country string No The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value.
address_region string No The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value.
postal_code string No The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value.
intent string No Background context describing buyer's intent (e.g., 'looking for a gift under $50', 'need something durable for outdoor use'). Informs relevance, recommendations, and personalization.
language string No Preferred language for content. Use IETF BCP 47 language tags (e.g., 'en', 'fr-CA', 'zh-Hans'). For REST, equivalent to Accept-Language header—platforms SHOULD fall back to Accept-Language when this field is absent; when provided, overrides Accept-Language. Businesses MAY return content in a different language if unavailable.
currency string No Preferred currency (ISO 4217, e.g., 'EUR', 'USD'). Businesses determine presentment currency from context and authoritative signals; this hint MAY inform selection in multi-currency markets. Also serves as the denomination for price filter values — platforms SHOULD include this field when sending price filters. Response prices include explicit currency confirming the resolution.

Description

Name Type Required Description
plain string No Plain text content.
html string No HTML-formatted content. Security: Platforms MUST sanitize before rendering—strip scripts, event handlers, and untrusted elements. Treat all rich text as untrusted input.
markdown string No Markdown-formatted content.

Error Code

Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.

Error Response

Name Type Required Description
ucp any Yes UCP protocol metadata. Status MUST be 'error' for error response.
messages Array[Message] Yes Array of messages describing why the operation failed.
continue_url string No URL for buyer handoff or session recovery.

Expectation

Name Type Required Description
id string Yes Expectation identifier.
line_items Array[object] Yes Which line items and quantities are in this expectation.
method_type string Yes Delivery method type (shipping, pickup, digital).
Enum: shipping, pickup, digital
destination Postal Address Yes Delivery destination address.
description string No Human-readable delivery description (e.g., 'Arrives in 5-8 business days').
fulfillable_on string No When this expectation can be fulfilled: 'now' or ISO 8601 timestamp for future date (backorder, pre-order).

Fulfillment

Name Type Required Description
methods Array[Fulfillment Method] No Fulfillment methods for cart items.
available_methods Array[Fulfillment Available Method] No Inventory availability hints.

Fulfillment Available Method

Name Type Required Description
type string Yes Fulfillment method type this availability applies to.
Enum: shipping, pickup
line_item_ids Array[string] Yes Line items available for this fulfillment method.
fulfillable_on ['string', 'null'] No 'now' for immediate availability, or ISO 8601 date for future (preorders, transfers).
description string No Human-readable availability info (e.g., 'Available for pickup at Downtown Store today').

Fulfillment Destination

This object MUST be one of the following types: Shipping Destination, Retail Location.

Fulfillment Event

Name Type Required Description
id string Yes Fulfillment event identifier.
occurred_at string Yes RFC 3339 timestamp when this fulfillment event occurred.
type string Yes Fulfillment event type. Common values include: processing (preparing to ship), shipped (handed to carrier), in_transit (in delivery network), delivered (received by buyer), failed_attempt (delivery attempt failed), canceled (fulfillment canceled), undeliverable (cannot be delivered), returned_to_sender (returned to merchant).
line_items Array[object] Yes Which line items and quantities are fulfilled in this event.
tracking_number string No Carrier tracking number (required if type != processing).
tracking_url string No URL to track this shipment (required if type != processing).
carrier string No Carrier name (e.g., 'FedEx', 'USPS').
description string No Human-readable description of the shipment status or delivery information (e.g., 'Delivered to front door', 'Out for delivery').

Fulfillment Group

Name Type Required Description
id string Yes Group identifier for referencing merchant-generated groups in updates.
line_item_ids Array[string] Yes Line item IDs included in this group/package.
options Array[Fulfillment Option] No Available fulfillment options for this group.
selected_option_id ['string', 'null'] No ID of the selected fulfillment option for this group.

Fulfillment Method

Name Type Required Description
id string Yes Unique fulfillment method identifier.
type string Yes Fulfillment method type.
Enum: shipping, pickup
line_item_ids Array[string] Yes Line item IDs fulfilled via this method.
destinations Array[Fulfillment Destination] No Available destinations. For shipping: addresses. For pickup: retail locations.
selected_destination_id ['string', 'null'] No ID of the selected destination.
groups Array[Fulfillment Group] No Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method.

Fulfillment Option

Name Type Required Description
id string Yes Unique fulfillment option identifier.
title string Yes Short label (e.g., 'Express Shipping', 'Curbside Pickup').
description string No Complete context for buyer decision (e.g., 'Arrives Dec 12-15 via FedEx').
carrier string No Carrier name (for shipping).
earliest_fulfillment_time string No Earliest fulfillment date.
latest_fulfillment_time string No Latest fulfillment date.
totals Array[Total] Yes Fulfillment option totals breakdown.

Input Correlation

Name Type Required Description
id string Yes The identifier from the lookup request that resolved to this variant.
match string No How the request identifier resolved to this variant. Well-known values: exact (input directly identifies this variant, e.g., variant ID, SKU), featured (server selected this variant as representative, e.g., product ID resolved to best match). Businesses MAY implement and provide additional resolution strategies.

Item

Name Type Required Description
id string Yes The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.
title string Yes Product title.
price Amount Yes Unit price in ISO 4217 minor units.
image_url string No Product image URI.

Line Item

Name Type Required Description
id string Yes
item Item Yes
quantity integer Yes Quantity of the item being purchased.
totals Array[Total] Yes Line item totals breakdown.
parent_id string No Parent line item identifier for any nested structures.
Name Type Required Description
type string Yes Type of link. Well-known values: privacy_policy, terms_of_service, refund_policy, shipping_policy, faq. Consumers SHOULD handle unknown values gracefully by displaying them using the title field or omitting the link.
url string Yes The actual URL pointing to the content to be displayed.
title string No Optional display text for the link. When provided, use this instead of generating from type.

Media

Name Type Required Description
type string Yes Media type. Well-known values: image, video, model_3d.
url string Yes URL to the media resource.
alt_text string No Accessibility text describing the media.
width integer No Width in pixels (for images/video).
height integer No Height in pixels (for images/video).

Merchant Fulfillment Config

Name Type Required Description
allows_multi_destination object No Permits multiple destinations per method type.
allows_method_combinations Array[array] No Allowed method type combinations.

Message

This object MUST be one of the following types: Message Error, Message Warning, Message Info.

Message Error

Name Type Required Description
type string Yes Constant = error. Message type discriminator.
code Error Code Yes Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.
path string No RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]).
content_type string No Content format, default = plain.
Enum: plain, markdown
content string Yes Human-readable message.
severity string Yes Reflects the resource state and recommended action. 'recoverable': platform can resolve by modifying inputs and retrying via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules. 'unrecoverable': no valid resource exists to act on, retry with new resource or inputs. Errors with 'requires_' severity contribute to 'status: requires_escalation'.
Enum:* recoverable, requires_buyer_input, requires_buyer_review, unrecoverable

Message Info

Name Type Required Description
type string Yes Constant = info. Message type discriminator.
path string No RFC 9535 JSONPath to the component the message refers to.
code string No Info code for programmatic handling.
content_type string No Content format, default = plain.
Enum: plain, markdown
content string Yes Human-readable message.

Message Warning

Name Type Required Description
type string Yes Constant = warning. Message type discriminator.
path string No JSONPath (RFC 9535) to related field (e.g., $.line_items[0]).
code string Yes Warning code. Machine-readable identifier for the warning type (e.g., final_sale, prop65, fulfillment_changed, age_restricted, etc.).
content string Yes Human-readable warning message that MUST be displayed.
content_type string No Content format, default = plain.
Enum: plain, markdown

Option Value

Name Type Required Description
label string Yes Display text for this option value (e.g., 'Small', 'Blue').

Order Confirmation

Name Type Required Description
id string Yes Unique order identifier.
permalink_url string Yes Permalink to access the order on merchant site.

Order Line Item

Name Type Required Description
id string Yes Line item identifier.
item Item Yes Product data (id, title, price, image_url).
quantity object Yes Quantity tracking. Both total and fulfilled are derived from events.
totals Array[Total] Yes Line item totals breakdown.
status string Yes Derived status: fulfilled if quantity.fulfilled == quantity.total, partial if quantity.fulfilled > 0, otherwise processing.
Enum: processing, partial, fulfilled
parent_id string No Parent line item identifier for any nested structures.

Pagination

Cursor-based pagination for list operations.

Payment Credential

Name Type Required Description
type string Yes The credential type discriminator. Specific schemas will constrain this to a constant value.

Payment Identity

Name Type Required Description
access_token string Yes Unique identifier for this participant, obtained during onboarding with the tokenizer.

Payment Instrument

Name Type Required Description
id string Yes A unique identifier for this instrument instance, assigned by the platform.
handler_id string Yes The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition.
type string Yes The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value.
billing_address Postal Address No The billing address associated with this payment method.
credential Payment Credential No The base definition for any payment credential. Handlers define specific credential types.
display object No Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.

Platform Fulfillment Config

Name Type Required Description
supports_multi_group boolean No Enables multiple groups per method.

Postal Address

Name Type Required Description
extended_address string No An address extension such as an apartment number, C/O or alternative name.
street_address string No The street address.
address_locality string No The locality in which the street address is, and which is in the region. For example, Mountain View.
address_region string No The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division.
address_country string No The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used.
postal_code string No The postal code. For example, 94043.
first_name string No Optional. First name of the contact associated with the address.
last_name string No Optional. Last name of the contact associated with the address.
phone_number string No Optional. Phone number of the contact associated with the address.

Price

Name Type Required Description
amount Amount Yes Amount in ISO 4217 minor units. Use 0 for free items.
currency string Yes ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').

Price Filter

Name Type Required Description
min Amount No Minimum price in ISO 4217 minor units.
max Amount No Maximum price in ISO 4217 minor units.

Price Range

Name Type Required Description
min Price Yes Minimum price in the range.
max Price Yes Maximum price in the range.

Product

Name Type Required Description
id string Yes Global ID (GID) uniquely identifying this product.
handle string No URL-safe slug for SEO-friendly URLs (e.g., 'blue-runner-pro'). Use id for stable API references.
title string Yes Product title.
description Description Yes Product description in one or more formats.
url string No Canonical product page URL.
categories Array[Category] No Product categories with optional taxonomy identifiers.
price_range Price Range Yes Price range across all variants.
list_price_range Price Range No List price range before discounts (for strikethrough display).
media Array[Media] No Product media (images, videos, 3D models). First item is the featured media for listings.
options Array[Product Option] No Product options (Size, Color, etc.).
variants Array[Variant] Yes Purchasable variants of this product. First item is the featured variant for listings.
rating Rating No Aggregate product rating.
tags Array[string] No Product tags for categorization and search.
metadata object No Business-defined custom data extending the standard product model.

Product Option

Name Type Required Description
name string Yes Option name (e.g., 'Size', 'Color').
values Array[Option Value] Yes Available values for this option.

Rating

Name Type Required Description
value number Yes Average rating value.
scale_min number No Minimum value on the rating scale (e.g., 1 for 1-5 stars).
scale_max number Yes Maximum value on the rating scale (e.g., 5 for 5-star).
count integer No Number of reviews contributing to the rating.

Retail Location

Name Type Required Description
id string Yes Unique location identifier.
name string Yes Location name (e.g., store name).
address Postal Address No Physical address of the location.

Search Filters

Name Type Required Description
categories Array[string] No Filter by product categories (OR logic — matches products in any listed categories). Values match against the value field in product category entries. Valid values can be discovered from the categories field in search results, merchant documentation, or standard taxonomies that businesses may align with.
price Price Filter No Price range filter denominated in context.currency. When context.currency matches the presentment currency, businesses apply the filter directly. When it differs, businesses SHOULD convert filter values to the presentment currency before applying; if conversion is not supported, businesses MAY ignore the filter and SHOULD indicate this via a message. When context.currency is absent, filter denomination is ambiguous and businesses MAY ignore it.

Selected Option

Name Type Required Description
name string Yes Option name (e.g., 'Size').
label string Yes Selected option label (e.g., 'Large').

Shipping Destination

Name Type Required Description
extended_address string No An address extension such as an apartment number, C/O or alternative name.
street_address string No The street address.
address_locality string No The locality in which the street address is, and which is in the region. For example, Mountain View.
address_region string No The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division.
address_country string No The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used.
postal_code string No The postal code. For example, 94043.
first_name string No Optional. First name of the contact associated with the address.
last_name string No Optional. Last name of the contact associated with the address.
phone_number string No Optional. Phone number of the contact associated with the address.
id string Yes ID specific to this shipping destination.

Token Credential

Name Type Required Description
type string Yes The credential type discriminator. Specific schemas will constrain this to a constant value.
type string Yes The specific type of token produced by the handler (e.g., 'stripe_token').
token string Yes The token value.

Total

Name Type Required Description
type string Yes Type of total categorization.
Enum: items_discount, subtotal, discount, fulfillment, tax, fee, total
display_text string No Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').
amount Amount Yes If type == total, sums subtotal - discount + fulfillment + tax + fee. Should be >= 0. Amount in ISO 4217 minor units.

Variant

Name Type Required Description
id string Yes Global ID (GID) uniquely identifying this variant. Used as item.id in checkout.
sku string No Business-assigned identifier for inventory and fulfillment.
barcodes Array[object] No Industry-standard product identifiers for cross-reference and correlation.
handle string No URL-safe variant handle/slug.
title string Yes Variant display title (e.g., 'Blue / Large').
description Description Yes Variant description in one or more formats.
url string No Canonical variant page URL.
categories Array[Category] No Variant categories with optional taxonomy identifiers.
price Price Yes Current selling price.
list_price Price No List price before discounts (for strikethrough display).
unit_price object No Price per standard unit of measurement. MAY be omitted when unit pricing does not apply.
availability object No Variant availability for purchase.
selected_options Array[Selected Option] No Option selections that define this variant.
media Array[Media] No Variant media (images, videos, 3D models). First item is the featured media for listings.
rating Rating No Variant rating.
tags Array[string] No Variant tags for categorization and search.
metadata object No Business-defined custom data extending the standard variant model.
seller object No Optional seller context for this variant.

Selected Payment Instrument

Name Type Required Description
id string Yes A unique identifier for this instrument instance, assigned by the platform.
handler_id string Yes The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition.
type string Yes The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value.
billing_address object No The billing address associated with this payment method.
credential object No The base definition for any payment credential. Handlers define specific credential types.
display object No Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.
selected boolean No Whether this instrument is selected by the user.

Pagination Request

Name Type Required Description
cursor string No Opaque cursor from previous response.
limit integer No Requested page size. Implementations MAY clamp to a lower maximum.

Pagination Response

Name Type Required Description
cursor string No Cursor to fetch the next page of results. MUST be present when has_next_page is true.
has_next_page boolean Yes Whether more results are available.
total_count integer No Total number of matching items, if available.

Error Code

Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.

Extension Schemas

AP2 Mandate Extension

Merchant Authorization

JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: <base64url-header>..<base64url-signature>. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload.

Pattern: ^[A-Za-z0-9_-]+\.\.[A-Za-z0-9_-]+$

Checkout Mandate

SD-JWT+kb credential in ap2.checkout_mandate. Proving user authorization for the checkout. Contains the full checkout including ap2.merchant_authorization.

Pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+(~[A-Za-z0-9_-]+)*$

Ap2 With Merchant Authorization

Name Type Required Description
merchant_authorization string No Merchant's signature proving checkout terms are authentic.

Ap2 With Checkout Mandate

Name Type Required Description
checkout_mandate string No SD-JWT+kb proving user authorized this checkout.

Checkout with AP2 Mandate

Name Type Required Description
ucp any Yes UCP metadata for checkout responses.
id string Yes Unique identifier of the checkout session.
line_items Array[object] Yes List of line items being checked out.
buyer object No Representation of the buyer.
status string Yes Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.
Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency string Yes ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals Array[object] Yes Different cart totals.
messages Array[object] No List of messages with error and info about the checkout session state.
links Array[object] Yes Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at string No RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url string No URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment object No Payment configuration containing handlers.
order object No Details about an order created for this checkout session.
ap2 any No

AP2 Error Code

Error codes specific to AP2 mandate verification.

Enum: mandate_required, agent_missing_key, mandate_invalid_signature, mandate_expired, mandate_scope_mismatch, merchant_authorization_invalid, merchant_authorization_missing

Name Type Required Description
analytics boolean No Consent for analytics and performance tracking.
preferences boolean No Consent for storing user preferences.
marketing boolean No Consent for marketing communications.
sale_of_data boolean No Consent for selling data to third parties (CCPA).
Name Type Required Description
first_name string No First name of the buyer.
last_name string No Last name of the buyer.
email string No Email of the buyer.
phone_number string No E.164 standard.
consent object No Consent tracking fields.
Name Type Required Description
ucp any Yes UCP metadata for checkout responses.
id string Yes Unique identifier of the checkout session.
line_items Array[object] Yes List of line items being checked out.
buyer object No Representation of the buyer.
status string Yes Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.
Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency string Yes ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals Array[object] Yes Different cart totals.
messages Array[object] No List of messages with error and info about the checkout session state.
links Array[object] Yes Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at string No RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url string No URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment object No Payment configuration containing handlers.
order object No Details about an order created for this checkout session.
buyer any No Buyer with consent tracking.

Discount Extension

Allocation

Name Type Required Description
path string Yes JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping').
amount integer Yes Amount allocated to this target in ISO 4217 minor units.

Applied Discount

Name Type Required Description
code string No The discount code. Omitted for automatic discounts.
title string Yes Human-readable discount name (e.g., 'Summer Sale 20% Off').
amount integer Yes Total discount amount in ISO 4217 minor units.
automatic boolean No True if applied automatically by merchant rules (no code required).
method string No Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value.
Enum: each, across
priority integer No Stacking order for discount calculation. Lower numbers applied first (1 = first).
allocations Array[object] No Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount.

Discounts Object

Name Type Required Description
codes Array[string] No Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.
applied Array[object] No Discounts successfully applied (code-based and automatic).

Checkout with Discount

Name Type Required Description
ucp any Yes UCP metadata for checkout responses.
id string Yes Unique identifier of the checkout session.
line_items Array[object] Yes List of line items being checked out.
buyer object No Representation of the buyer.
status string Yes Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.
Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency string Yes ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals Array[object] Yes Different cart totals.
messages Array[object] No List of messages with error and info about the checkout session state.
links Array[object] Yes Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at string No RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url string No URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment object No Payment configuration containing handlers.
order object No Details about an order created for this checkout session.
discounts object No Discount codes input and applied discounts output.

Fulfillment Extension

Fulfillment Option

Name Type Required Description
id string Yes Unique fulfillment option identifier.
title string Yes Short label (e.g., 'Express Shipping', 'Curbside Pickup').
description string No Complete context for buyer decision (e.g., 'Arrives Dec 12-15 via FedEx').
carrier string No Carrier name (for shipping).
earliest_fulfillment_time string No Earliest fulfillment date.
latest_fulfillment_time string No Latest fulfillment date.
totals Array[object] Yes Fulfillment option totals breakdown.

Fulfillment Group

Name Type Required Description
id string Yes Group identifier for referencing merchant-generated groups in updates.
line_item_ids Array[string] Yes Line item IDs included in this group/package.
options Array[object] No Available fulfillment options for this group.
selected_option_id ['string', 'null'] No ID of the selected fulfillment option for this group.

Fulfillment Method

Name Type Required Description
id string Yes Unique fulfillment method identifier.
type string Yes Fulfillment method type.
Enum: shipping, pickup
line_item_ids Array[string] Yes Line item IDs fulfilled via this method.
destinations Array[object] No Available destinations. For shipping: addresses. For pickup: retail locations.
selected_destination_id ['string', 'null'] No ID of the selected destination.
groups Array[object] No Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method.

Fulfillment Available Method

Name Type Required Description
type string Yes Fulfillment method type this availability applies to.
Enum: shipping, pickup
line_item_ids Array[string] Yes Line items available for this fulfillment method.
fulfillable_on ['string', 'null'] No 'now' for immediate availability, or ISO 8601 date for future (preorders, transfers).
description string No Human-readable availability info (e.g., 'Available for pickup at Downtown Store today').

Fulfillment

Name Type Required Description
methods Array[object] No Fulfillment methods for cart items.
available_methods Array[object] No Inventory availability hints.

Checkout with Fulfillment

Name Type Required Description
ucp any Yes UCP metadata for checkout responses.
id string Yes Unique identifier of the checkout session.
line_items Array[object] Yes List of line items being checked out.
buyer object No Representation of the buyer.
status string Yes Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.
Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency string Yes ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals Array[object] Yes Different cart totals.
messages Array[object] No List of messages with error and info about the checkout session state.
links Array[object] Yes Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at string No RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url string No URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment object No Payment configuration containing handlers.
order object No Details about an order created for this checkout session.
fulfillment object No Fulfillment details.

Dev.Ucp.Shopping.Fulfillment

No properties defined.

UCP Metadata

The following schemas define the structure of UCP metadata used in discovery and responses.

Platform Discovery Profile

The top-level structure of a platform profile document (hosted at a URI advertised by the platform).

Name Type Required Description
version string Yes UCP version in YYYY-MM-DD format.
status string No Application-level status of the UCP operation.
Enum: success, error
services object No Service registry keyed by reverse-domain name.
capabilities object No Capability registry keyed by reverse-domain name.
payment_handlers object No Payment handler registry keyed by reverse-domain name.
services any Yes
capabilities any No
payment_handlers any Yes

Business Discovery Profile

The top-level structure of a business discovery document (/.well-known/ucp).

Name Type Required Description
version string Yes UCP version in YYYY-MM-DD format.
status string No Application-level status of the UCP operation.
Enum: success, error
services object No Service registry keyed by reverse-domain name.
capabilities object No Capability registry keyed by reverse-domain name.
payment_handlers object No Payment handler registry keyed by reverse-domain name.
supported_versions object No Previous protocol versions this business supports, mapped to profile URIs. Businesses that support older protocol versions SHOULD advertise each version and link to its profile. Each URI points to a complete, self-contained profile for that version. When omitted, only version is supported.
services any Yes
capabilities any No
payment_handlers any Yes

Checkout Response Metadata

The ucp object included in checkout responses.

Name Type Required Description
version string Yes UCP version in YYYY-MM-DD format.
status string No Application-level status of the UCP operation.
Enum: success, error
services object No Service registry keyed by reverse-domain name.
capabilities object No Capability registry keyed by reverse-domain name.
payment_handlers object No Payment handler registry keyed by reverse-domain name.
services any No
capabilities any No
payment_handlers any Yes

Cart Response Metadata

The ucp object included in cart responses.

Name Type Required Description
version string Yes UCP version in YYYY-MM-DD format.
status string No Application-level status of the UCP operation.
Enum: success, error
services object No Service registry keyed by reverse-domain name.
capabilities object No Capability registry keyed by reverse-domain name.
payment_handlers object No Payment handler registry keyed by reverse-domain name.
capabilities any No

Order Response Metadata

The ucp object included in order responses or events.

Name Type Required Description
version string Yes UCP version in YYYY-MM-DD format.
status string No Application-level status of the UCP operation.
Enum: success, error
services object No Service registry keyed by reverse-domain name.
capabilities object No Capability registry keyed by reverse-domain name.
payment_handlers object No Payment handler registry keyed by reverse-domain name.
capabilities any No

Capability

This object describes a single capability or extension. It appears in the capabilities array in discovery profiles and responses, with slightly different required fields in each context.

Capability (Discovery)

As seen in discovery profiles.

Name Type Required Description
version string No Entity version in YYYY-MM-DD format.
spec string Yes URL to human-readable specification document.
schema string Yes URL to JSON Schema defining this entity's structure and payloads.
id string No Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config object No Entity-specific configuration. Structure defined by each entity's schema.
extends OneOf[] No Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.

Capability (Response)

As seen in response messages.

Name Type Required Description
version string Yes Entity version in YYYY-MM-DD format.
spec string No URL to human-readable specification document.
schema string No URL to JSON Schema defining this entity's structure and payloads.
id string No Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config object No Entity-specific configuration. Structure defined by each entity's schema.
extends OneOf[] No Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.