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 |
any |
Yes |
UCP metadata for cart responses. No payment handlers needed pre-checkout. |
| 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. |
| signals |
Signals |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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 |
Totals |
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. Supports batch retrieval (lookup_catalog) and single-product detail (get_product).
Catalog Search
Product catalog search capability.
Checkout
| Name |
Type |
Required |
Description |
| ucp |
any |
Yes |
UCP metadata for checkout responses. |
| 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. |
| signals |
Signals |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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 |
Totals |
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 |
any |
Yes |
UCP metadata for order responses. No payment handlers needed post-purchase. |
| id |
string |
Yes |
Unique order identifier. |
| label |
string |
No |
Human-readable label for identifying the order. MUST only be provided by the business. |
| 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 |
Line items representing what was purchased — can change post-order via edits or exchanges. |
| fulfillment |
object |
Yes |
Fulfillment data: buyer expectations and what actually happened. |
| adjustments |
Array[Adjustment] |
No |
Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment. |
| currency |
string |
Yes |
ISO 4217 currency code. MUST match the currency from the originating checkout session. |
| totals |
Totals |
Yes |
Different totals for the order. |
| messages |
Array[Message] |
No |
Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform. |
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). |
| totals |
Array[Total] |
No |
Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges). |
| 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 |
No |
A unique identifier for this instrument instance, assigned by the platform. |
| handler_id |
string |
No |
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. |
| eligibility |
Array[Reverse Domain Name] |
No |
Buyer claims about eligible benefits such as loyalty membership, payment instrument perks, and similar. Recognized claims MAY inform the Business response (e.g., member-only product availability, adjusted pricing in catalog, provisional discounts at cart or checkout). Businesses MUST ignore unrecognized values without error. Values MUST use reverse-domain naming (e.g., 'com.example.loyalty_gold', 'org.school.student') and MUST be non-identifying. |
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. |
Detail Option Value
| Name |
Type |
Required |
Description |
| id |
string |
No |
Optional server-assigned identifier for this option value. When present in a selected_option, the server SHOULD use it for matching instead of label. |
| label |
string |
Yes |
Display text for this option value (e.g., 'Small', 'Blue'). |
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
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. |
| 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. |
Link
| 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. |
| 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 |
| presentation |
string |
No |
Rendering contract for this warning. 'notice' (default): platform MUST display, MAY dismiss. 'disclosure': platform MUST display in proximity to the path-referenced component, MUST NOT hide or auto-dismiss. See specification for full contract. |
| image_url |
string |
No |
URL to a required visual element (e.g., warning symbol, energy class label). |
| url |
string |
No |
Reference URL for more information (e.g., regulatory site, registry entry, policy page). |
Option Value
| Name |
Type |
Required |
Description |
| id |
string |
No |
Optional server-assigned identifier for this option value. When present in a selected_option, the server SHOULD use it for matching instead of label. |
| 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. |
| label |
string |
No |
Human-readable label for identifying the order. MUST only be provided by the business. |
| 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 for the line item. |
| totals |
Array[Total] |
Yes |
Line item totals breakdown. |
| status |
string |
Yes |
Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing.
Enum: processing, partial, fulfilled, removed |
| parent_id |
string |
No |
Parent line item identifier for any nested structures. |
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. |
| 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. |
Reverse Domain Name
Reverse-domain identifier used for collision-safe namespacing of capabilities, services, handlers, eligibility claims, and extension-contributed keys. Must contain at least two dot-separated segments (e.g., 'dev.ucp.shopping.checkout', 'com.example.loyalty_gold').
Pattern: ^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_]*)+$
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'). |
| id |
string |
No |
Optional option value identifier from option_value.id. When present, the server SHOULD use it for matching; name and label remain required for display. |
| 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. |
Signals
| Name |
Type |
Required |
Description |
| dev.ucp.buyer_ip |
string |
No |
Client's IP address (IPv4 or IPv6). |
| dev.ucp.user_agent |
string |
No |
Client's HTTP User-Agent header or equivalent. |
Signed 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). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).
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 |
|
|
|
|
Totals
| Name |
Type |
Required |
Description |
|
|
|
|
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
A payment instrument with selection state.
| 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 parameters for requests.
| 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 information in responses.
| 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.
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.
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
AP2 extension data including merchant authorization.
| Name |
Type |
Required |
Description |
| merchant_authorization |
string |
No |
Merchant's signature proving checkout terms are authentic. |
Ap2 With Checkout Mandate
AP2 extension data including checkout mandate.
| Name |
Type |
Required |
Description |
| checkout_mandate |
string |
No |
SD-JWT+kb proving user authorized this checkout. |
Checkout with AP2 Mandate
Checkout extended with AP2 mandate support.
| 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. |
| context |
object |
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. |
| signals |
object |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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[any] |
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.
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
Buyer Consent Extension
Consent
User consent states for data processing
| 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). |
Buyer with Consent
Buyer object extended with consent tracking.
| 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. |
Checkout with Buyer Consent
Checkout extended with consent tracking via buyer object.
| 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. |
| context |
object |
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. |
| signals |
object |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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[any] |
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
Breakdown of how a discount amount was allocated to a specific target.
| 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
A discount that was successfully applied.
| 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). |
| provisional |
boolean |
No |
True if this discount requires additional verification. |
| eligibility |
string |
No |
The eligibility claim accepted by the Business for this discount. Corresponds to a value from context.eligibility. Omitted for code-based and non-eligibility automatic discounts. |
| allocations |
Array[object] |
No |
Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. |
Discounts Object
Discount codes input and applied discounts output.
| 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). |
Cart with Discount
Cart extended with discount capability.
| Name |
Type |
Required |
Description |
| ucp |
any |
Yes |
UCP metadata for cart responses. No payment handlers needed pre-checkout. |
| id |
string |
Yes |
Unique cart identifier. |
| line_items |
Array[object] |
Yes |
Cart line items. Same structure as checkout. Full replacement on update. |
| context |
object |
No |
Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted. |
| signals |
object |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| buyer |
object |
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[any] |
Yes |
Estimated cost breakdown. May be partial if shipping/tax not yet calculable. |
| messages |
Array[object] |
No |
Validation messages, warnings, or informational notices. |
| links |
Array[object] |
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. |
| discounts |
object |
No |
Discount codes input and applied discounts output. |
Checkout with Discount
Checkout extended with discount capability.
| 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. |
| context |
object |
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. |
| signals |
object |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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[any] |
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
A fulfillment option within a group (e.g., Standard Shipping $5, Express $15).
| 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
A merchant-generated package/group of line items with fulfillment options.
| 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
A fulfillment method (shipping or pickup) with destinations and groups.
| 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
Inventory availability hint for a fulfillment method type.
| 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
Container for fulfillment methods and availability.
| Name |
Type |
Required |
Description |
| methods |
Array[object] |
No |
Fulfillment methods for cart items. |
| available_methods |
Array[object] |
No |
Inventory availability hints. |
Checkout with Fulfillment
Checkout extended with hierarchical 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. |
| context |
object |
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. |
| signals |
object |
No |
Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. |
| 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[any] |
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. |
No properties defined.
The following schemas define the structure of UCP metadata used in discovery
and responses.
The top-level structure of a platform profile document (hosted at a URI advertised by the platform).
Full UCP metadata for platform-level configuration. Hosted at a URI advertised by the platform in request headers.
| 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 |
Yes |
Service registry keyed by reverse-domain name. |
| capabilities |
object |
No |
Capability registry keyed by reverse-domain name. |
| payment_handlers |
object |
Yes |
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).
UCP metadata for business/merchant-level configuration. Subset of platform schema with business-specific settings.
| 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 |
Yes |
Service registry keyed by reverse-domain name. |
| capabilities |
object |
No |
Capability registry keyed by reverse-domain name. |
| payment_handlers |
object |
Yes |
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.
UCP metadata for 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 |
Yes |
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.
UCP metadata for cart responses. No payment handlers needed pre-checkout.
| 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.
UCP metadata for order responses. No payment handlers needed post-purchase.
| 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.
Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching.
| Name |
Type |
Required |
Description |
| version |
string |
Yes |
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.
Capability reference in responses. Only name/version required to confirm active capabilities.
| 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. |