diff --git a/docs/index.md b/docs/index.md index 65a24306..c73f3e3f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -326,7 +326,7 @@ image: assets/banner.png { "ucp": { ... }, "id": "order_123456789", - "checkout_id": "chk_123456789", + "checkouts": [{ "id": "chk_123456789", "created_at": "..." }], "permalink_url": ..., "line_items": [ ... ], "fulfillment": { @@ -367,8 +367,8 @@ image: assets/banner.png "type": "refund", "occurred_at": "2026-01-12T14:30:00Z", "status": "completed", - "line_items": [{ "id": "li_1", "quantity": 1 }], - "amount": 26550, + "line_items": [{ "id": "li_1", "quantity": -1 }], + "totals": [{ "type": "total", "amount": -26550 }], "description": "Defective item" } ], diff --git a/docs/specification/order.md b/docs/specification/order.md index 66472d96..51f8ec16 100644 --- a/docs/specification/order.md +++ b/docs/specification/order.md @@ -31,17 +31,20 @@ Orders have three main components: **Line Items** — what was purchased at checkout: * Includes current quantity counts (total, fulfilled) +* Can change post-order (e.g. order edits, exchanges) **Fulfillment** — how items get delivered: * **Expectations** — buyer-facing *promises* about when/how items will arrive * **Events** (append-only log) — what actually happened (e.g. 👕 was shipped) -**Adjustments** (append-only log) — post-order events independent of fulfillment: +**Adjustments** — post-order events independent of fulfillment: * Typically money movements (refunds, returns, credits, disputes, cancellations) * Can be any post-order change * Can happen before, during, or after fulfillment +* Businesses may append new entries or update existing ones in place + (e.g. a single `return` adjustment can transition from `pending` to `completed`) ## Data Model @@ -50,7 +53,7 @@ Orders have three main components: Line items reflect what was purchased at checkout and their current state: * Item details (product, price, quantity ordered) -* Quantity counts and status are derived +* Quantity counts and fulfillment status ### Fulfillment @@ -83,7 +86,7 @@ Expectations can be split, merged, or adjusted post-order. For example: ### Adjustments -**Adjustments** are an append-only log of events that exist independently of +**Adjustments** are post-order events that exist independently of fulfillment: * Type is an open string field - businesses can use any values that make sense @@ -91,7 +94,9 @@ fulfillment: `price_adjustment`, `dispute`, `cancellation`) * Can be any post-order change * Optionally link to line items (or order-level for things like shipping refunds) -* Include amount when relevant +* Quantities and amounts are signed—negative for reductions (returns, refunds), + positive for additions (exchanges) +* Include totals breakdown when relevant * Can happen at any time regardless of fulfillment status ## Schema @@ -103,7 +108,6 @@ fulfillment: ### Order Line Item Line items reflect what was purchased at checkout and their current state. -Status and quantity counts should reflect the event logs. {{ schema_fields('order_line_item', 'order') }} @@ -111,7 +115,8 @@ Status and quantity counts should reflect the event logs. ```json { - "total": 3, // Current total quantity + "original": 3, // Quantity from the original checkout + "total": 3, // Current total (may differ after edits/exchanges) "fulfilled": 2 // What has been fulfilled } ``` @@ -165,13 +170,15 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`, } }, "id": "order_abc123", - "checkout_id": "checkout_xyz789", + "checkouts": [ + { "id": "checkout_xyz789", "created_at": "2025-01-05T09:00:00Z" } + ], "permalink_url": "https://business.com/orders/abc123", "line_items": [ { "id": "li_shoes", "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 }, - "quantity": { "total": 3, "fulfilled": 3 }, + "quantity": { "original": 3, "total": 3, "fulfilled": 3 }, "totals": [ {"type": "subtotal", "amount": 9000}, {"type": "total", "amount": 9000} @@ -181,7 +188,7 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`, { "id": "li_shirts", "item": { "id": "prod_shirts", "title": "Cotton T-Shirt", "price": 2000 }, - "quantity": { "total": 2, "fulfilled": 0 }, + "quantity": { "original": 2, "total": 2, "fulfilled": 0 }, "totals": [ {"type": "subtotal", "amount": 4000}, {"type": "total", "amount": 4000} @@ -238,8 +245,10 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`, "type": "refund", "occurred_at": "2025-01-10T14:30:00Z", "status": "completed", - "line_items": [{ "id": "li_shoes", "quantity": 1 }], - "amount": 3000, + "line_items": [{ "id": "li_shoes", "quantity": -1 }], + "totals": [ + { "type": "total", "amount": -3000 } + ], "description": "Defective item" } ], diff --git a/generate_ts_schema_types.js b/generate_ts_schema_types.js index 1b0120d9..144f4c0e 100644 --- a/generate_ts_schema_types.js +++ b/generate_ts_schema_types.js @@ -2,7 +2,7 @@ const fs = require('node:fs'); const path = require('node:path'); const { compile } = require('json-schema-to-typescript'); -const SOURCE_ROOT = path.resolve(__dirname, 'spec'); +const SOURCE_ROOT = path.resolve(__dirname, 'source'); const OUTPUT_FILE = path.resolve(__dirname, './generated/schema-types.ts'); const WRAPPER_NAME = 'SCHEMA_WRAPPER'; diff --git a/generated/schema-types.ts b/generated/schema-types.ts index 92f481ca..ff8654b8 100644 --- a/generated/schema-types.ts +++ b/generated/schema-types.ts @@ -10,715 +10,284 @@ /** * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "merchant_authorization". */ -export type MerchantAuthorizationCompleteRequest = string; +export type MerchantAuthorization = string; /** * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "checkout_mandate". */ -export type CheckoutMandateCompleteRequest = string; -/** - * Checkout extended with AP2 mandate support. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithAP2MandateCompleteRequest = CheckoutCompleteRequest & { - ap2?: Ap2WithMerchantAuthorization & Ap2WithCheckoutMandate; - [k: string]: unknown; -}; -/** - * Matches a specific instrument type based on validation logic. - */ -export type PaymentInstrument = CardPaymentInstrument; -/** - * A basic card payment instrument with visible card details. Can be inherited by a handler's instrument schema to define handler-specific display details or more complex credential structures. - */ -export type CardPaymentInstrument = PaymentInstrumentBase & { - /** - * Indicates this is a card payment instrument. - */ - type: 'card'; - /** - * The card brand/network (e.g., visa, mastercard, amex). - */ - brand: string; - /** - * Last 4 digits of the card number. - */ - last_digits: string; - /** - * The month of the card's expiration date (1-12). - */ - expiry_month?: number; - /** - * The year of the card's expiration date. - */ - expiry_year?: number; - /** - * An optional rich text description of the card to display to the user (e.g., 'Visa ending in 1234, expires 12/2025'). - */ - rich_text_description?: string; - /** - * An optional URI to a rich image representing the card (e.g., card art provided by the issuer). - */ - rich_card_art?: string; - [k: string]: unknown; -}; -/** - * Container for sensitive payment data. Use the specific schema matching the 'type' field. - */ -export type PaymentCredential = TokenCredentialResponse | CardCredential; -/** - * Error codes specific to AP2 mandate verification. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "error_code". - */ -export type AP2ErrorCodeCompleteRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; -/** - * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. - * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "merchant_authorization". - */ -export type MerchantAuthorizationCreateRequest = string; -/** - * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. - * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout_mandate". - */ -export type CheckoutMandateCreateRequest = string; -/** - * Checkout extended with AP2 mandate support. - * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithAP2MandateCreateRequest = CheckoutCreateRequest & { - [k: string]: unknown; -}; -/** - * Error codes specific to AP2 mandate verification. - * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "error_code". - */ -export type AP2ErrorCodeCreateRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; -/** - * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. - * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "merchant_authorization". - */ -export type MerchantAuthorizationUpdateRequest = string; -/** - * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. - * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout_mandate". - */ -export type CheckoutMandateUpdateRequest = string; -/** - * Checkout extended with AP2 mandate support. - * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithAP2MandateUpdateRequest = CheckoutUpdateRequest & { - [k: string]: unknown; -}; -/** - * Error codes specific to AP2 mandate verification. - * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "error_code". - */ -export type AP2ErrorCodeUpdateRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; +export type CheckoutMandate = string; /** * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. - * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "merchant_authorization". */ -export type MerchantAuthorizationResponse = string; +export type MerchantAuthorization1 = string; /** * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. - * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "checkout_mandate". */ -export type CheckoutMandateResponse = string; +export type CheckoutMandate1 = string; /** * Checkout extended with AP2 mandate support. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithAP2MandateResponse = CheckoutResponse & { - ap2?: Ap2WithMerchantAuthorization1 & Ap2WithCheckoutMandate1; - [k: string]: unknown; -}; -/** - * Capability reference in responses. Only name/version required to confirm active capabilities. - */ -export type CapabilityResponse = Base & { - [k: string]: unknown; -}; -/** - * Container for error, warning, or info messages. - */ -export type Message = MessageError | MessageWarning | MessageInfo; -/** - * Error codes specific to AP2 mandate verification. - * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "error_code". - */ -export type AP2ErrorCodeResponse = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; -/** - * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "buyer". - */ -export type BuyerWithConsentCompleteRequest = Buyer & { - consent?: Consent; - [k: string]: unknown; -}; -/** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithBuyerConsentCompleteRequest = CheckoutCompleteRequest & { - [k: string]: unknown; -}; -/** - * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "buyer". + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema + * via the `definition` "dev.ucp.shopping.checkout". */ -export type BuyerWithConsentCreateRequest = Buyer & { - consent?: Consent1; - [k: string]: unknown; -}; -/** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithBuyerConsentCreateRequest = CheckoutCreateRequest & { - buyer?: BuyerWithConsentCreateRequest; - [k: string]: unknown; -}; -/** - * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "buyer". - */ -export type BuyerWithConsentUpdateRequest = Buyer & { - consent?: Consent2; - [k: string]: unknown; -}; -/** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithBuyerConsentUpdateRequest = CheckoutUpdateRequest & { - buyer?: BuyerWithConsentUpdateRequest; - [k: string]: unknown; -}; -/** - * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "buyer". - */ -export type BuyerWithConsentResponse = Buyer & { - consent?: Consent3; - [k: string]: unknown; -}; -/** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithBuyerConsentResponse = CheckoutResponse & { - buyer?: BuyerWithConsentResponse; - [k: string]: unknown; -}; -/** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithDiscountCompleteRequest = CheckoutCompleteRequest & { - [k: string]: unknown; -}; -/** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithDiscountCreateRequest = CheckoutCreateRequest & { - discounts?: DiscountsObject; - [k: string]: unknown; -}; -/** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithDiscountUpdateRequest = CheckoutUpdateRequest & { - discounts?: DiscountsObject1; - [k: string]: unknown; -}; -/** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithDiscountResponse = CheckoutResponse & { - discounts?: DiscountsObject2; - [k: string]: unknown; -}; -/** - * A destination for fulfillment. - */ -export type FulfillmentDestinationRequest = ShippingDestinationRequest | RetailLocationRequest; -/** - * Shipping destination. - */ -export type ShippingDestinationRequest = PostalAddress & { - /** - * ID specific to this shipping destination. - */ - id?: string; - [k: string]: unknown; -}; -/** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithFulfillmentCompleteRequest = CheckoutCompleteRequest & { - [k: string]: unknown; -}; -/** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithFulfillmentCreateRequest = CheckoutCreateRequest & { - fulfillment?: FulfillmentRequest; - [k: string]: unknown; -}; -/** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithFulfillmentUpdateRequest = CheckoutUpdateRequest & { - fulfillment?: FulfillmentRequest; - [k: string]: unknown; -}; -/** - * A destination for fulfillment. - */ -export type FulfillmentDestinationResponse = ShippingDestinationResponse | RetailLocationResponse; -/** - * Shipping destination. - */ -export type ShippingDestinationResponse = PostalAddress & { - /** - * ID specific to this shipping destination. - */ - id: string; - [k: string]: unknown; -}; -/** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". - */ -export type CheckoutWithFulfillmentResponse = CheckoutResponse & { - fulfillment?: FulfillmentResponse; +export type CheckoutWithAP2Mandate = Checkout & { + ap2?: Ap2WithMerchantAuthorization & Ap2WithCheckoutMandate; [k: string]: unknown; }; - /** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. - */ -export declare interface AP2MandateExtensionCompleteRequest { - [k: string]: unknown; -} -/** - * AP2 extension data including merchant authorization. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "ap2_with_merchant_authorization". - */ -export declare interface Ap2WithMerchantAuthorization { - [k: string]: unknown; -} -/** - * AP2 extension data including checkout mandate. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "ap2_with_checkout_mandate". - */ -export declare interface Ap2WithCheckoutMandate { - checkout_mandate?: CheckoutMandateCompleteRequest; - [k: string]: unknown; -} -/** - * Base checkout schema. Extensions compose onto this using allOf. - */ -export declare interface CheckoutCompleteRequest { - payment: PaymentCompleteRequest; - [k: string]: unknown; -} -/** - * Payment configuration containing handlers. - */ -export declare interface PaymentCompleteRequest { - /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. - */ - selected_instrument_id?: string; - /** - * 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. - */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -/** - * The base definition for any payment instrument. It links the instrument to a specific Merchant configuration (handler_id) and defines common fields like billing address. - */ -export declare interface PaymentInstrumentBase { - /** - * A unique identifier for this instrument instance, assigned by the Agent. Used to reference this specific instrument in the 'payment.selected_instrument_id' field. - */ - id: string; - /** - * The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition. - */ - handler_id: string; - /** - * The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value. - */ - type: string; - billing_address?: PostalAddress; - credential?: PaymentCredential; - [k: string]: unknown; -} -export declare interface PostalAddress { - /** - * An address extension such as an apartment number, C/O or alternative name. - */ - extended_address?: string; - /** - * The street address. - */ - street_address?: string; - /** - * The locality in which the street address is, and which is in the region. For example, Mountain View. - */ - address_locality?: string; - /** - * 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_region?: string; - /** - * 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. - */ - address_country?: string; - /** - * The postal code. For example, 94043. - */ - postal_code?: string; - /** - * Optional. First name of the contact associated with the address. - */ - first_name?: string; - /** - * Optional. Last name of the contact associated with the address. - */ - last_name?: string; - /** - * Optional. Phone number of the contact associated with the address. - */ - phone_number?: string; - [k: string]: unknown; -} -/** - * Base token credential schema. Concrete payment handlers may extend this schema with additional fields and define their own constraints. - */ -export declare interface TokenCredentialResponse { - /** - * The specific type of token produced by the handler (e.g., 'stripe_token'). - */ - type: string; - [k: string]: unknown; -} -/** - * A card credential containing sensitive payment card details including raw Primary Account Numbers (PANs). This credential type MUST NOT be used for checkout, only with payment handlers that tokenize or encrypt credentials. CRITICAL: Both parties handling CardCredential (sender and receiver) MUST be PCI DSS compliant. Transmission MUST use HTTPS/TLS with strong cipher suites. - */ -export declare interface CardCredential { - /** - * The credential type identifier for card credentials. - */ - type: 'card'; - /** - * The type of card number. Network tokens are preferred with fallback to FPAN. See PCI Scope for more details. - */ - card_number_type: 'fpan' | 'network_token' | 'dpan'; - /** - * Card number. - */ - number?: string; - /** - * The month of the card's expiration date (1-12). - */ - expiry_month?: number; - /** - * The year of the card's expiration date. - */ - expiry_year?: number; - /** - * Cardholder name. - */ - name?: string; - /** - * Card CVC number. - */ - cvc?: string; - /** - * Cryptogram provided with network tokens. - */ - cryptogram?: string; - /** - * Electronic Commerce Indicator / Security Level Indicator provided with network tokens. - */ - eci_value?: string; - [k: string]: unknown; -} -/** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. + * UCP metadata for checkout responses. */ -export declare interface AP2MandateExtensionCreateRequest { +export type UCPCheckoutResponseSchema = Base & { + services?: { + [k: string]: ServiceResponseSchema[]; + }; + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + payment_handlers: { + [k: string]: PaymentHandlerResponseSchema[]; + }; [k: string]: unknown; -} +}; /** - * Base checkout schema. Extensions compose onto this using allOf. + * Service binding in API responses. Includes per-resource transport configuration via typed config. */ -export declare interface CheckoutCreateRequest { +export type ServiceResponseSchema = (Entity & { /** - * List of line items being checked out. + * Transport protocol for this service binding. */ - line_items: LineItemCreateRequest[]; - buyer?: Buyer; + transport: 'rest' | 'mcp' | 'a2a' | 'embedded'; /** - * ISO 4217 currency code. + * Endpoint URL for this transport binding. */ - currency: string; - payment?: PaymentCreateRequest; + endpoint?: string; [k: string]: unknown; -} +}) & + ( + | { + transport?: 'rest'; + [k: string]: unknown; + } + | { + transport?: 'mcp'; + [k: string]: unknown; + } + | { + transport?: 'a2a'; + [k: string]: unknown; + } + | { + transport?: 'embedded'; + config?: EmbeddedTransportConfig; + [k: string]: unknown; + } + ); /** - * Line item object. Expected to use the currency of the parent object. + * Capability reference in responses. Only name/version required to confirm active capabilities. */ -export declare interface LineItemCreateRequest { - item: ItemCreateRequest; +export type CapabilityResponseSchema = Entity & { /** - * Quantity of the item being purchased. + * Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions. */ - quantity: number; + extends?: string | [string, ...string[]]; [k: string]: unknown; -} -export declare interface ItemCreateRequest { - /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. - */ - id: string; +}; +/** + * Handler reference in responses. May include full config state for runtime usage of the handler. + */ +export type PaymentHandlerResponseSchema = Entity & { [k: string]: unknown; -} -export declare interface Buyer { - /** - * First name of the buyer. - */ - first_name?: string; - /** - * Last name of the buyer. - */ - last_name?: string; - /** - * Email of the buyer. - */ - email?: string; +} & { /** - * E.164 standard. + * Instrument types this handler supports, with optional constraints. When absent, every instrument should be considered available. + * + * @minItems 1 */ - phone_number?: string; + available_instruments?: [AvailablePaymentInstrument, ...AvailablePaymentInstrument[]]; [k: string]: unknown; -} +}; /** - * Payment configuration containing handlers. + * 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). */ -export declare interface PaymentCreateRequest { - /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. - */ - selected_instrument_id?: string; +export type Amount = number; +/** + * 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). + */ +export type Amount1 = number; +/** + * Container for error, warning, or info messages. + */ +export type Message = MessageError | MessageWarning | MessageInfo; +/** + * Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted. + */ +export type ErrorCode = string; +/** + * A payment instrument with selection state. + */ +export type SelectedPaymentInstrument = PaymentInstrument & { /** - * 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. + * Whether this instrument is selected by the user. */ - instruments?: PaymentInstrument[]; + selected?: boolean; [k: string]: unknown; -} +}; /** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. + * Error codes specific to AP2 mandate verification. + * + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema + * via the `definition` "error_code". + */ +export type AP2ErrorCode = + | 'mandate_required' + | 'agent_missing_key' + | 'mandate_invalid_signature' + | 'mandate_expired' + | 'mandate_scope_mismatch' + | 'merchant_authorization_invalid' + | 'merchant_authorization_missing'; +/** + * Buyer object extended with consent tracking. + * + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema + * via the `definition` "buyer". */ -export declare interface AP2MandateExtensionUpdateRequest { +export type BuyerWithConsent = Buyer1 & { + consent?: Consent; [k: string]: unknown; -} +}; /** - * Base checkout schema. Extensions compose onto this using allOf. + * Checkout extended with consent tracking via buyer object. + * + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema + * via the `definition` "dev.ucp.shopping.checkout". */ -export declare interface CheckoutUpdateRequest { - /** - * Unique identifier of the checkout session. - */ - id: string; - /** - * List of line items being checked out. - */ - line_items: LineItemUpdateRequest[]; - buyer?: Buyer; - /** - * ISO 4217 currency code. - */ - currency: string; - payment?: PaymentUpdateRequest; +export type CheckoutWithBuyerConsent = Checkout & { + buyer?: BuyerWithConsent1; [k: string]: unknown; -} +}; /** - * Line item object. Expected to use the currency of the parent object. + * Buyer object extended with consent tracking. */ -export declare interface LineItemUpdateRequest { - id?: string; - item: ItemUpdateRequest; - /** - * Quantity of the item being purchased. - */ - quantity: number; +export type BuyerWithConsent1 = Buyer1 & { + consent?: Consent; + [k: string]: unknown; +}; +/** + * UCP metadata for cart responses. No payment handlers needed pre-checkout. + */ +export type UCPCartResponseSchema = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + [k: string]: unknown; +}; +/** + * Checkout extended with cart capability. Adds cart_id to create_checkout for cart-to-checkout conversion. + * + * This interface was referenced by `Cart`'s JSON-Schema + * via the `definition` "checkout". + */ +export type CheckoutWithCart = Checkout & { /** - * Parent line item identifier for any nested structures. + * Cart ID to convert to checkout. Business MUST use cart contents (line_items, context, buyer) and MUST ignore overlapping fields in checkout payload. */ - parent_id?: string; + cart_id?: string; [k: string]: unknown; -} -export declare interface ItemUpdateRequest { +}; +/** + * 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). + */ +export type Amount2 = number; +/** + * UCP metadata for catalog responses. + */ +export type UCPCatalogResponseSchema = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + [k: string]: unknown; +}; +/** + * Checkout extended with discount capability. + * + * This interface was referenced by `DiscountExtension`'s JSON-Schema + * via the `definition` "dev.ucp.shopping.checkout". + */ +export type CheckoutWithDiscount = Checkout & { + discounts?: DiscountsObject; + [k: string]: unknown; +}; +/** + * A destination for fulfillment. + */ +export type FulfillmentDestination = ShippingDestination | RetailLocation; +/** + * Shipping destination. + */ +export type ShippingDestination = PostalAddress & { /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. + * ID specific to this shipping destination. */ id: string; [k: string]: unknown; -} +}; /** - * Payment configuration containing handlers. + * Checkout extended with hierarchical fulfillment. + * + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema + * via the `definition` "dev.ucp.shopping.checkout". */ -export declare interface PaymentUpdateRequest { - /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. - */ - selected_instrument_id?: string; - /** - * 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. - */ - instruments?: PaymentInstrument[]; +export type CheckoutWithFulfillment = Checkout & { + fulfillment?: Fulfillment1; [k: string]: unknown; -} +}; +/** + * UCP metadata for order responses. No payment handlers needed post-purchase. + */ +export type UCPOrderResponseSchema = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + [k: string]: unknown; +}; + /** * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. */ -export declare interface AP2MandateExtensionResponse { +export declare interface AP2MandateExtension { [k: string]: unknown; } /** * AP2 extension data including merchant authorization. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "ap2_with_merchant_authorization". */ -export declare interface Ap2WithMerchantAuthorization1 { - merchant_authorization?: MerchantAuthorizationResponse; +export declare interface Ap2WithMerchantAuthorization { + merchant_authorization?: MerchantAuthorization1; [k: string]: unknown; } /** * AP2 extension data including checkout mandate. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "ap2_with_checkout_mandate". */ -export declare interface Ap2WithCheckoutMandate1 { - checkout_mandate?: CheckoutMandateResponse; +export declare interface Ap2WithCheckoutMandate { + checkout_mandate?: CheckoutMandate1; [k: string]: unknown; } /** * Base checkout schema. Extensions compose onto this using allOf. */ -export declare interface CheckoutResponse { - ucp: UCPCheckoutResponse; +export declare interface Checkout { + ucp: UCPCheckoutResponseSchema; /** * Unique identifier of the checkout session. */ @@ -726,8 +295,9 @@ export declare interface CheckoutResponse { /** * List of line items being checked out. */ - line_items: LineItemResponse[]; + line_items: LineItem[]; buyer?: Buyer; + context?: Context; /** * Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. */ @@ -739,13 +309,13 @@ export declare interface CheckoutResponse { | 'completed' | 'canceled'; /** - * ISO 4217 currency code. + * ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency. */ currency: string; /** * Different cart totals. */ - totals: TotalResponse[]; + totals: Total[]; /** * List of messages with error and info about the checkout session state. */ @@ -762,59 +332,132 @@ export declare interface CheckoutResponse { * URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements. */ continue_url?: string; - payment: PaymentResponse; + payment?: Payment; order?: OrderConfirmation; [k: string]: unknown; } /** - * UCP metadata for checkout responses. + * Base UCP metadata with shared properties for all schema types. */ -export declare interface UCPCheckoutResponse { +export declare interface Base { /** - * UCP protocol version in YYYY-MM-DD format. + * UCP version in YYYY-MM-DD format. */ version: string; /** - * Active capabilities for this response. + * Application-level status of the UCP operation. */ - capabilities: CapabilityResponse[]; - [k: string]: unknown; -} -export declare interface Base { + status?: 'success' | 'error'; + /** + * Service registry keyed by reverse-domain name. + */ + services?: { + [k: string]: Array; + }; /** - * Stable capability identifier in reverse-domain notation (e.g., dev.ucp.shopping.checkout). Used in capability negotiation. + * Capability registry keyed by reverse-domain name. */ - name?: string; + capabilities?: { + [k: string]: (Entity & { + /** + * Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions. + */ + extends?: string | [string, ...string[]]; + [k: string]: unknown; + })[]; + }; + /** + * Payment handler registry keyed by reverse-domain name. + */ + payment_handlers?: { + [k: string]: Array; + }; + [k: string]: unknown; +} +/** + * Shared foundation for all UCP entities. + */ +export declare interface Entity { /** - * UCP protocol version in YYYY-MM-DD format. + * UCP version in YYYY-MM-DD format. */ - version?: string; + version: string; /** * URL to human-readable specification document. */ spec?: string; /** - * URL to JSON Schema for this capability's payload. + * URL to JSON Schema defining this entity's structure and payloads. */ schema?: string; /** - * Parent capability this extends. Present for extensions, absent for root capabilities. + * Unique identifier for this entity instance. Used to disambiguate when multiple instances exist. */ - extends?: string; + id?: string; /** - * Capability-specific configuration (structure defined by each capability). + * Entity-specific configuration. Structure defined by each entity's schema. */ config?: { [k: string]: unknown; }; [k: string]: unknown; } +/** + * An instrument type available from a payment handler with optional constraints. + */ +export declare interface AvailablePaymentInstrument { + /** + * The instrument type identifier (e.g., 'card', 'gift_card'). References an instrument schema's type constant. + */ + type: string; + /** + * Constraints on this instrument type. Structure depends on instrument type and active capabilities. + */ + constraints?: { + [k: string]: unknown; + }; + [k: string]: unknown; +} +/** + * Per-checkout configuration for embedded transport binding. Allows businesses to vary ECP availability and delegations based on cart contents, agent authorization, or policy. + */ +export declare interface EmbeddedTransportConfig { + /** + * Delegations the business allows. At service-level, declares available delegations. In checkout responses, confirms accepted delegations for this session. + */ + delegate?: string[]; + /** + * Color schemes the business supports. Hosts use ec_color_scheme query parameter to request a scheme from this list. + */ + color_scheme?: Array<'light' | 'dark'>; + [k: string]: unknown; +} /** * Line item object. Expected to use the currency of the parent object. */ -export declare interface LineItemResponse { +export declare interface LineItem { id: string; - item: ItemResponse; + item: Item; /** * Quantity of the item being purchased. */ @@ -822,33 +465,30 @@ export declare interface LineItemResponse { /** * Line item totals breakdown. */ - totals: TotalResponse[]; + totals: Total[]; /** * Parent line item identifier for any nested structures. */ parent_id?: string; [k: string]: unknown; } -export declare interface ItemResponse { +export declare interface Item { /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. + * 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. */ id: string; /** * Product title. */ title: string; - /** - * Unit price in minor (cents) currency units. - */ - price: number; + price: Amount; /** * Product image URI. */ image_url?: string; [k: string]: unknown; } -export declare interface TotalResponse { +export declare interface Total { /** * Type of total categorization. */ @@ -857,10 +497,56 @@ export declare interface TotalResponse { * Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery'). */ display_text?: string; + amount: Amount1; + [k: string]: unknown; +} +export declare interface Buyer { + /** + * First name of the buyer. + */ + first_name?: string; + /** + * Last name of the buyer. + */ + last_name?: string; + /** + * Email of the buyer. + */ + email?: string; + /** + * E.164 standard. + */ + phone_number?: string; + [k: string]: unknown; +} +/** + * 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. + */ +export declare interface Context { + /** + * 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_country?: string; + /** + * 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. + */ + address_region?: string; + /** + * The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. + */ + postal_code?: string; + /** + * 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. + */ + intent?: string; + /** + * 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. + */ + language?: string; /** - * If type == total, sums subtotal - discount + fulfillment + tax + fee. Should be >= 0. Amount in minor (cents) currency units. + * 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. */ - amount: number; + currency?: string; [k: string]: unknown; } export declare interface MessageError { @@ -868,10 +554,7 @@ export declare interface MessageError { * Message type discriminator. */ type: 'error'; - /** - * Error code. Possible values include: missing, invalid, out_of_stock, payment_declined, requires_sign_in, requires_3ds, requires_identity_linking. Freeform codes also allowed. - */ - code: string; + code: ErrorCode; /** * RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]). */ @@ -885,9 +568,9 @@ export declare interface MessageError { */ content: string; /** - * Declares who resolves this error. 'recoverable': agent can fix 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 (checkout complete). Errors with 'requires_*' severity contribute to 'status: requires_escalation'. + * 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'. */ - severity: 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review'; + severity: 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review' | 'unrecoverable'; [k: string]: unknown; } export declare interface MessageWarning { @@ -942,61 +625,98 @@ export declare interface Link { */ type: string; /** - * The actual URL pointing to the content to be displayed. + * The actual URL pointing to the content to be displayed. + */ + url: string; + /** + * Optional display text for the link. When provided, use this instead of generating from type. + */ + title?: string; + [k: string]: unknown; +} +/** + * Payment configuration containing handlers. + */ +export declare interface Payment { + /** + * 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. + */ + instruments?: SelectedPaymentInstrument[]; + [k: string]: unknown; +} +/** + * The base definition for any payment instrument. It links the instrument to a specific payment handler. + */ +export declare interface PaymentInstrument { + /** + * A unique identifier for this instrument instance, assigned by the platform. + */ + id: string; + /** + * The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition. + */ + handler_id: string; + /** + * The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value. */ - url: string; + type: string; + billing_address?: PostalAddress; + credential?: PaymentCredential; /** - * Optional display text for the link. When provided, use this instead of generating from type. + * Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler. */ - title?: string; + display?: { + [k: string]: unknown; + }; [k: string]: unknown; } -/** - * Payment configuration containing handlers. - */ -export declare interface PaymentResponse { +export declare interface PostalAddress { /** - * Processing configurations that define how payment instruments can be collected. Each handler specifies a tokenization or payment collection strategy. + * An address extension such as an apartment number, C/O or alternative name. */ - handlers: PaymentHandlerResponse[]; + extended_address?: string; /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. + * The street address. */ - selected_instrument_id?: string; + street_address?: string; /** - * 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. + * The locality in which the street address is, and which is in the region. For example, Mountain View. */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -export declare interface PaymentHandlerResponse { + address_locality?: string; /** - * The unique identifier for this handler instance within the payment.handlers. Used by payment instruments to reference which handler produced them. + * 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. */ - id: string; + address_region?: string; /** - * The specification name using reverse-DNS format. For example, dev.ucp.delegate_payment. + * 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. */ - name: string; + address_country?: string; /** - * UCP protocol version in YYYY-MM-DD format. + * The postal code. For example, 94043. */ - version: string; + postal_code?: string; /** - * A URI pointing to the technical specification or schema that defines how this handler operates. + * Optional. First name of the contact associated with the address. */ - spec: string; + first_name?: string; /** - * A URI pointing to a JSON Schema used to validate the structure of the config object. + * Optional. Last name of the contact associated with the address. */ - config_schema: string; - instrument_schemas: string[]; + last_name?: string; /** - * A dictionary containing provider-specific configuration details, such as merchant IDs, supported networks, or gateway credentials. + * Optional. Phone number of the contact associated with the address. */ - config: { - [k: string]: unknown; - }; + phone_number?: string; + [k: string]: unknown; +} +/** + * The base definition for any payment credential. Handlers define specific credential types. + */ +export declare interface PaymentCredential { + /** + * The credential type discriminator. Specific schemas will constrain this to a constant value. + */ + type: string; [k: string]: unknown; } /** @@ -1016,13 +736,13 @@ export declare interface OrderConfirmation { /** * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. */ -export declare interface BuyerConsentExtensionCompleteRequest { +export declare interface BuyerConsentExtension { [k: string]: unknown; } /** * User consent states for data processing * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema * via the `definition` "consent". */ export declare interface Consent { @@ -1044,619 +764,629 @@ export declare interface Consent { sale_of_data?: boolean; [k: string]: unknown; } -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionCreateRequest { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent1 { +export declare interface Buyer1 { /** - * Consent for analytics and performance tracking. + * First name of the buyer. */ - analytics?: boolean; + first_name?: string; /** - * Consent for storing user preferences. + * Last name of the buyer. */ - preferences?: boolean; + last_name?: string; /** - * Consent for marketing communications. + * Email of the buyer. */ - marketing?: boolean; + email?: string; /** - * Consent for selling data to third parties (CCPA). + * E.164 standard. */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionUpdateRequest { + phone_number?: string; [k: string]: unknown; } /** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "consent". + * Shopping cart with estimated pricing before checkout. Lightweight pre-purchase exploration with no payment info or complex status states. */ -export declare interface Consent2 { +export declare interface Cart { + ucp: UCPCartResponseSchema; /** - * Consent for analytics and performance tracking. + * Unique cart identifier. */ - analytics?: boolean; + id: string; /** - * Consent for storing user preferences. + * Cart line items. Same structure as checkout. Full replacement on update. */ - preferences?: boolean; + line_items: LineItem[]; + context?: Context1; + buyer?: Buyer2; /** - * Consent for marketing communications. + * ISO 4217 currency code. Determined by merchant based on context or geo-IP. */ - marketing?: boolean; + currency: string; /** - * Consent for selling data to third parties (CCPA). + * Estimated cost breakdown. May be partial if shipping/tax not yet calculable. */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionResponse { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent3 { + totals: Total[]; /** - * Consent for analytics and performance tracking. + * Validation messages, warnings, or informational notices. */ - analytics?: boolean; + messages?: Message[]; /** - * Consent for storing user preferences. + * Optional merchant links (policies, FAQs). */ - preferences?: boolean; + links?: Link[]; /** - * Consent for marketing communications. + * URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows. */ - marketing?: boolean; + continue_url?: string; /** - * Consent for selling data to third parties (CCPA). + * Cart expiry timestamp (RFC 3339). Optional. */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionCompleteRequest { + expires_at?: string; [k: string]: unknown; } /** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "allocation". + * 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. */ -export declare interface Allocation { +export declare interface Context1 { /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). + * 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. */ - path: string; + address_country?: string; /** - * Amount allocated to this target in minor (cents) currency units. + * 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. */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount { + address_region?: string; /** - * The discount code. Omitted for automatic discounts. + * The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. */ - code?: string; + postal_code?: string; /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). + * 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. */ - title: string; + intent?: string; /** - * Total discount amount in minor (cents) currency units. + * 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. */ - amount: number; + language?: string; /** - * True if applied automatically by merchant rules (no code required). + * 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. */ - automatic?: boolean; + currency?: string; + [k: string]: unknown; +} +export declare interface Buyer2 { /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. + * First name of the buyer. */ - method?: 'each' | 'across'; + first_name?: string; /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). + * Last name of the buyer. */ - priority?: number; + last_name?: string; /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. + * Email of the buyer. */ - allocations?: Allocation[]; + email?: string; + /** + * E.164 standard. + */ + phone_number?: string; [k: string]: unknown; } /** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. + * Product/variant lookup by identifier capability. */ -export declare interface DiscountExtensionCreateRequest { +export declare interface CatalogLookup { [k: string]: unknown; } /** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "allocation". + * A purchasable variant of a product with specific option selections. */ -export declare interface Allocation1 { +export declare interface Variant { /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). + * Global ID (GID) uniquely identifying this variant. Used as item.id in checkout. */ - path: string; + id: string; /** - * Amount allocated to this target in minor (cents) currency units. + * Business-assigned identifier for inventory and fulfillment. */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount1 { + sku?: string; /** - * The discount code. Omitted for automatic discounts. + * Industry-standard product identifiers for cross-reference and correlation. */ - code?: string; + barcodes?: Array<{ + /** + * Barcode standard. Well-known values: UPC, EAN, ISBN, GTIN, JAN. + */ + type: string; + /** + * Barcode value. + */ + value: string; + [k: string]: unknown; + }>; /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). + * URL-safe variant handle/slug. + */ + handle?: string; + /** + * Variant display title (e.g., 'Blue / Large'). */ title: string; + description: Description; /** - * Total discount amount in minor (cents) currency units. + * Canonical variant page URL. */ - amount: number; + url?: string; /** - * True if applied automatically by merchant rules (no code required). + * Variant categories with optional taxonomy identifiers. */ - automatic?: boolean; + categories?: Category[]; + price: Price; + list_price?: Price; /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. + * Price per standard unit of measurement. MAY be omitted when unit pricing does not apply. */ - method?: 'each' | 'across'; + unit_price?: { + amount: Amount2; + /** + * ISO 4217 currency code. + */ + currency: string; + /** + * Product quantity in packaging (e.g., 750ml bottle). + */ + measure: { + /** + * Package quantity. + */ + value: number; + /** + * Unit of measurement. + */ + unit: string; + [k: string]: unknown; + }; + /** + * Denominator for unit price display (e.g., per 100ml, per 1kg). + */ + reference: { + /** + * Reference quantity. + */ + value: number; + /** + * Unit of measurement. + */ + unit: string; + [k: string]: unknown; + }; + [k: string]: unknown; + }; /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). + * Variant availability for purchase. */ - priority?: number; + availability?: { + /** + * Whether this variant can be purchased. See status for fulfillment details. + */ + available?: boolean; + /** + * Qualifies available with fulfillment state. Well-known values: `in_stock`, `backorder`, `preorder`, `out_of_stock`, `discontinued`. + */ + status?: string; + [k: string]: unknown; + }; /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. + * Option selections that define this variant. */ - allocations?: Allocation1[]; - [k: string]: unknown; -} -/** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "discounts_object". - */ -export declare interface DiscountsObject { + selected_options?: SelectedOption[]; /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. + * Variant media (images, videos, 3D models). First item is the featured media for listings. */ - codes?: string[]; + media?: Media[]; + rating?: Rating; /** - * Discounts successfully applied (code-based and automatic). + * Variant tags for categorization and search. */ - applied?: AppliedDiscount1[]; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionUpdateRequest { - [k: string]: unknown; -} -/** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "allocation". - */ -export declare interface Allocation2 { + tags?: string[]; /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). + * Business-defined custom data extending the standard variant model. */ - path: string; + metadata?: { + [k: string]: unknown; + }; /** - * Amount allocated to this target in minor (cents) currency units. + * Optional seller context for this variant. */ - amount: number; + seller?: { + /** + * Seller display name. + */ + name?: string; + /** + * Seller policy and information links. + */ + links?: Link[]; + [k: string]: unknown; + }; [k: string]: unknown; } /** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "applied_discount". + * Description content in one or more formats. At least one format must be provided. */ -export declare interface AppliedDiscount2 { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; - /** - * Total discount amount in minor (cents) currency units. - */ - amount: number; - /** - * True if applied automatically by merchant rules (no code required). - */ - automatic?: boolean; +export declare interface Description { /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. + * Plain text content. */ - method?: 'each' | 'across'; + plain?: string; /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). + * HTML-formatted content. Security: Platforms MUST sanitize before rendering—strip scripts, event handlers, and untrusted elements. Treat all rich text as untrusted input. */ - priority?: number; + html?: string; /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. + * Markdown-formatted content. */ - allocations?: Allocation2[]; + markdown?: string; [k: string]: unknown; } /** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "discounts_object". + * A product category with optional taxonomy identifier. */ -export declare interface DiscountsObject1 { +export declare interface Category { /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. + * Category value or path (e.g., 'Apparel > Shirts', '1604'). */ - codes?: string[]; + value: string; /** - * Discounts successfully applied (code-based and automatic). + * Source taxonomy. Well-known values: `google_product_category`, `shopify`, `merchant`. */ - applied?: AppliedDiscount2[]; + taxonomy?: string; [k: string]: unknown; } /** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. + * Price with explicit currency. */ -export declare interface DiscountExtensionResponse { +export declare interface Price { + amount: Amount2; + /** + * ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP'). + */ + currency: string; [k: string]: unknown; } /** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "allocation". + * A specific option selection on a variant (e.g., Size: Large). */ -export declare interface Allocation3 { +export declare interface SelectedOption { /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). + * Option name (e.g., 'Size'). */ - path: string; + name: string; /** - * Amount allocated to this target in minor (cents) currency units. + * Selected option label (e.g., 'Large'). */ - amount: number; + label: string; [k: string]: unknown; } /** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "applied_discount". + * Product media item (image, video, etc.). */ -export declare interface AppliedDiscount3 { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; +export declare interface Media { /** - * Total discount amount in minor (cents) currency units. + * Media type. Well-known values: `image`, `video`, `model_3d`. */ - amount: number; + type: string; /** - * True if applied automatically by merchant rules (no code required). + * URL to the media resource. */ - automatic?: boolean; + url: string; /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. + * Accessibility text describing the media. */ - method?: 'each' | 'across'; + alt_text?: string; /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). + * Width in pixels (for images/video). */ - priority?: number; + width?: number; /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. + * Height in pixels (for images/video). */ - allocations?: Allocation3[]; + height?: number; [k: string]: unknown; } /** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "discounts_object". + * Product rating aggregate. */ -export declare interface DiscountsObject2 { +export declare interface Rating { /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. + * Average rating value. */ - codes?: string[]; + value: number; /** - * Discounts successfully applied (code-based and automatic). + * Minimum value on the rating scale (e.g., 1 for 1-5 stars). */ - applied?: AppliedDiscount3[]; - [k: string]: unknown; -} -/** - * Extends Checkout with fulfillment support using methods, destinations, and groups. - */ -export declare interface FulfillmentExtensionCompleteRequest { + scale_min?: number; + /** + * Maximum value on the rating scale (e.g., 5 for 5-star). + */ + scale_max: number; + /** + * Number of reviews contributing to the rating. + */ + count?: number; [k: string]: unknown; } /** - * A fulfillment option within a group (e.g., Standard Shipping $5, Express $15). - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". + * Maps a request identifier to the variant it resolved to, with match semantics. */ -export declare interface FulfillmentOptionRequest { +export declare interface InputCorrelation { + /** + * The identifier from the lookup request that resolved to this variant. + */ + id: string; + /** + * 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. + */ + match?: string; [k: string]: unknown; } /** - * A merchant-generated package/group of line items with fulfillment options. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". + * 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. */ -export declare interface FulfillmentGroupCompleteRequest { +export declare interface Context2 { /** - * Group identifier for referencing merchant-generated groups in updates. + * 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. */ - id: string; + address_country?: string; /** - * ID of the selected fulfillment option for this group. + * 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. */ - selected_option_id?: string | null; + address_region?: string; + /** + * The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. + */ + postal_code?: string; + /** + * 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. + */ + intent?: string; + /** + * 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. + */ + language?: string; + /** + * 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. + */ + currency?: string; [k: string]: unknown; } /** - * A fulfillment method (shipping or pickup) with destinations and groups. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". + * A product in the catalog with variants and options. */ -export declare interface FulfillmentMethodCompleteRequest { +export declare interface Product { /** - * Unique fulfillment method identifier. + * Global ID (GID) uniquely identifying this product. */ id: string; /** - * Fulfillment method type. + * URL-safe slug for SEO-friendly URLs (e.g., 'blue-runner-pro'). Use id for stable API references. */ - type: 'shipping' | 'pickup'; + handle?: string; /** - * Line item IDs fulfilled via this method. + * Product title. */ - line_item_ids: string[]; + title: string; + description: Description; /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * Canonical product page URL. */ - destinations?: FulfillmentDestinationRequest[]; + url?: string; /** - * ID of the selected destination. + * Product categories with optional taxonomy identifiers. */ - selected_destination_id?: string | null; + categories?: Category[]; + price_range: PriceRange; + list_price_range?: PriceRange; /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Product media (images, videos, 3D models). First item is the featured media for listings. + */ + media?: Media[]; + /** + * Product options (Size, Color, etc.). + */ + options?: ProductOption[]; + /** + * Purchasable variants of this product. First item is the featured variant for listings. + * + * @minItems 1 + */ + variants: [Variant, ...Variant[]]; + rating?: Rating; + /** + * Product tags for categorization and search. */ - groups?: FulfillmentGroupCompleteRequest[]; + tags?: string[]; + /** + * Business-defined custom data extending the standard product model. + */ + metadata?: { + [k: string]: unknown; + }; [k: string]: unknown; } /** - * A pickup location (retail store, locker, etc.). + * A price range representing minimum and maximum values (e.g., across product variants). + */ +export declare interface PriceRange { + min: Price; + max: Price; + [k: string]: unknown; +} +/** + * A product option such as size, color, or material. */ -export declare interface RetailLocationRequest { +export declare interface ProductOption { /** - * Location name (e.g., store name). + * Option name (e.g., 'Size', 'Color'). */ name: string; - address?: PostalAddress; + /** + * Available values for this option. + * + * @minItems 1 + */ + values: [OptionValue, ...OptionValue[]]; [k: string]: unknown; } /** - * Inventory availability hint for a fulfillment method type. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". + * A selectable value for a product option. */ -export declare interface FulfillmentAvailableMethodRequest { +export declare interface OptionValue { + /** + * Display text for this option value (e.g., 'Small', 'Blue'). + */ + label: string; [k: string]: unknown; } /** - * Container for fulfillment methods and availability. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment". - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment". + * Product catalog search capability. */ -export declare interface FulfillmentRequest { - /** - * Fulfillment methods for cart items. - */ - methods?: FulfillmentMethodCreateRequest[]; +export declare interface CatalogSearch { [k: string]: unknown; } /** - * A fulfillment method (shipping or pickup) with destinations and groups. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". + * Filter criteria to narrow search results. All specified filters combine with AND logic. */ -export declare interface FulfillmentMethodCreateRequest { - /** - * Fulfillment method type. - */ - type: 'shipping' | 'pickup'; - /** - * Line item IDs fulfilled via this method. - */ - line_item_ids?: string[]; +export declare interface SearchFilters { /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * 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. */ - destinations?: FulfillmentDestinationRequest[]; + categories?: string[]; + price?: PriceFilter; + [k: string]: unknown; +} +/** + * 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. + */ +export declare interface PriceFilter { + min?: Amount2; + max?: Amount2; + [k: string]: unknown; +} +/** + * Pagination parameters for requests. + */ +export declare interface Request { /** - * ID of the selected destination. + * Opaque cursor from previous response. */ - selected_destination_id?: string | null; + cursor?: string; /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Requested page size. Implementations MAY clamp to a lower maximum. */ - groups?: FulfillmentGroupCreateRequest[]; + limit?: number; [k: string]: unknown; } /** - * A merchant-generated package/group of line items with fulfillment options. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". + * Pagination information in responses. */ -export declare interface FulfillmentGroupCreateRequest { +export declare interface Response { /** - * ID of the selected fulfillment option for this group. + * Cursor to fetch the next page of results. MUST be present when has_next_page is true. */ - selected_option_id?: string | null; + cursor?: string; + /** + * Whether more results are available. + */ + has_next_page: boolean; + /** + * Total number of matching items, if available. + */ + total_count?: number; [k: string]: unknown; } /** - * Extends Checkout with fulfillment support using methods, destinations, and groups. + * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. */ -export declare interface FulfillmentExtensionCreateRequest { +export declare interface DiscountExtension { [k: string]: unknown; } /** - * Extends Checkout with fulfillment support using methods, destinations, and groups. + * Breakdown of how a discount amount was allocated to a specific target. + * + * This interface was referenced by `DiscountExtension`'s JSON-Schema + * via the `definition` "allocation". */ -export declare interface FulfillmentExtensionUpdateRequest { +export declare interface Allocation { + /** + * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). + */ + path: string; + amount: Amount2; [k: string]: unknown; } /** - * A merchant-generated package/group of line items with fulfillment options. + * A discount that was successfully applied. * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". + * This interface was referenced by `DiscountExtension`'s JSON-Schema + * via the `definition` "applied_discount". */ -export declare interface FulfillmentGroupUpdateRequest { +export declare interface AppliedDiscount { /** - * Group identifier for referencing merchant-generated groups in updates. + * The discount code. Omitted for automatic discounts. */ - id: string; + code?: string; /** - * ID of the selected fulfillment option for this group. + * Human-readable discount name (e.g., 'Summer Sale 20% Off'). */ - selected_option_id?: string | null; - [k: string]: unknown; -} -/** - * A fulfillment method (shipping or pickup) with destinations and groups. - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". - */ -export declare interface FulfillmentMethodUpdateRequest { + title: string; + amount: Amount2; /** - * Unique fulfillment method identifier. + * True if applied automatically by merchant rules (no code required). */ - id: string; + automatic?: boolean; /** - * Line item IDs fulfilled via this method. + * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. */ - line_item_ids: string[]; + method?: 'each' | 'across'; /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * Stacking order for discount calculation. Lower numbers applied first (1 = first). */ - destinations?: FulfillmentDestinationRequest[]; + priority?: number; /** - * ID of the selected destination. + * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. */ - selected_destination_id?: string | null; + allocations?: Allocation[]; + [k: string]: unknown; +} +/** + * Discount codes input and applied discounts output. + */ +export declare interface DiscountsObject { /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. + */ + codes?: string[]; + /** + * Discounts successfully applied (code-based and automatic). */ - groups?: FulfillmentGroupUpdateRequest[]; + applied?: AppliedDiscount[]; [k: string]: unknown; } /** * Extends Checkout with fulfillment support using methods, destinations, and groups. */ -export declare interface FulfillmentExtensionResponse { +export declare interface FulfillmentExtension { [k: string]: unknown; } /** * A fulfillment option within a group (e.g., Standard Shipping $5, Express $15). * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_option". */ -export declare interface FulfillmentOptionResponse { +export declare interface FulfillmentOption { /** * Unique fulfillment option identifier. */ @@ -1684,16 +1414,16 @@ export declare interface FulfillmentOptionResponse { /** * Fulfillment option totals breakdown. */ - totals: TotalResponse[]; + totals: Total[]; [k: string]: unknown; } /** * A merchant-generated package/group of line items with fulfillment options. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_group". */ -export declare interface FulfillmentGroupResponse { +export declare interface FulfillmentGroup { /** * Group identifier for referencing merchant-generated groups in updates. */ @@ -1705,7 +1435,7 @@ export declare interface FulfillmentGroupResponse { /** * Available fulfillment options for this group. */ - options?: FulfillmentOptionResponse[]; + options?: FulfillmentOption[]; /** * ID of the selected fulfillment option for this group. */ @@ -1715,10 +1445,10 @@ export declare interface FulfillmentGroupResponse { /** * A fulfillment method (shipping or pickup) with destinations and groups. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_method". */ -export declare interface FulfillmentMethodResponse { +export declare interface FulfillmentMethod { /** * Unique fulfillment method identifier. */ @@ -1734,7 +1464,7 @@ export declare interface FulfillmentMethodResponse { /** * Available destinations. For shipping: addresses. For pickup: retail locations. */ - destinations?: FulfillmentDestinationResponse[]; + destinations?: FulfillmentDestination[]; /** * ID of the selected destination. */ @@ -1742,13 +1472,13 @@ export declare interface FulfillmentMethodResponse { /** * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. */ - groups?: FulfillmentGroupResponse[]; + groups?: FulfillmentGroup[]; [k: string]: unknown; } /** * A pickup location (retail store, locker, etc.). */ -export declare interface RetailLocationResponse { +export declare interface RetailLocation { /** * Unique location identifier. */ @@ -1763,10 +1493,10 @@ export declare interface RetailLocationResponse { /** * Inventory availability hint for a fulfillment method type. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_available_method". */ -export declare interface FulfillmentAvailableMethodResponse { +export declare interface FulfillmentAvailableMethod { /** * Fulfillment method type this availability applies to. */ @@ -1788,39 +1518,78 @@ export declare interface FulfillmentAvailableMethodResponse { /** * Container for fulfillment methods and availability. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment". */ -export declare interface FulfillmentResponse { +export declare interface Fulfillment { + /** + * Fulfillment methods for cart items. + */ + methods?: FulfillmentMethod[]; + /** + * Inventory availability hints. + */ + available_methods?: FulfillmentAvailableMethod[]; + [k: string]: unknown; +} +/** + * Container for fulfillment methods and availability. + */ +export declare interface Fulfillment1 { /** * Fulfillment methods for cart items. */ - methods?: FulfillmentMethodResponse[]; + methods?: FulfillmentMethod[]; /** * Inventory availability hints. */ - available_methods?: FulfillmentAvailableMethodResponse[]; + available_methods?: FulfillmentAvailableMethod[]; [k: string]: unknown; } /** - * Order schema with immutable line items, buyer-facing fulfillment expectations, and append-only event logs. + * Order schema with line items, buyer-facing fulfillment expectations, and event logs. */ export declare interface Order { - ucp: UCPOrderResponse; + ucp: UCPOrderResponseSchema; /** * Unique order identifier. */ id: string; /** - * Associated checkout ID for reconciliation. - */ - checkout_id: string; + * Associated checkout sessions. Orders reference one or more checkouts—order edits and exchanges create additional checkout sessions against the same order. + * + * @minItems 1 + */ + checkouts: [ + { + /** + * Unique identifier of the checkout session. + */ + id: string; + /** + * RFC 3339 timestamp when this checkout session was created. + */ + created_at: string; + [k: string]: unknown; + }, + ...{ + /** + * Unique identifier of the checkout session. + */ + id: string; + /** + * RFC 3339 timestamp when this checkout session was created. + */ + created_at: string; + [k: string]: unknown; + }[] + ]; /** * Permalink to access the order on merchant site. */ permalink_url: string; /** - * Immutable line items — source of truth for what was ordered. + * Line items representing what was purchased — can change post-order via edits or exchanges. */ line_items: OrderLineItem[]; /** @@ -1838,27 +1607,17 @@ export declare interface Order { [k: string]: unknown; }; /** - * Append-only event log of money movements (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment. + * Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment. */ adjustments?: Adjustment[]; /** - * Different totals for the order. - */ - totals: TotalResponse[]; - [k: string]: unknown; -} -/** - * UCP metadata for order responses. No payment handlers needed post-purchase. - */ -export declare interface UCPOrderResponse { - /** - * UCP protocol version in YYYY-MM-DD format. + * ISO 4217 currency code. MUST match the currency from the originating checkout session. */ - version: string; + currency?: string; /** - * Active capabilities for this response. + * Different totals for the order. */ - capabilities: CapabilityResponse[]; + totals: Total[]; [k: string]: unknown; } export declare interface OrderLineItem { @@ -1866,17 +1625,21 @@ export declare interface OrderLineItem { * Line item identifier. */ id: string; - item: ItemResponse; + item: Item; /** - * Quantity tracking. Both total and fulfilled are derived from events. + * Quantity tracking for the line item. */ quantity: { /** - * Current total quantity. + * Quantity from the original checkout (earliest created_at). Convenience property—avoids requiring a separate Checkout lookup. + */ + original?: number; + /** + * Current total quantity. May differ from original due to order edits or exchanges. */ total: number; /** - * Quantity fulfilled (sum from fulfillment events). + * Quantity fulfilled so far. */ fulfilled: number; [k: string]: unknown; @@ -1884,7 +1647,7 @@ export declare interface OrderLineItem { /** * Line item totals breakdown. */ - totals: TotalResponse[]; + totals: Total[]; /** * Derived status: fulfilled if quantity.fulfilled == quantity.total, partial if quantity.fulfilled > 0, otherwise processing. */ @@ -1981,7 +1744,7 @@ export declare interface FulfillmentEvent { [k: string]: unknown; } /** - * Append-only event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items. + * Post-order event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items. */ export declare interface Adjustment { /** @@ -2009,15 +1772,15 @@ export declare interface Adjustment { */ id: string; /** - * Quantity affected by this adjustment. + * Signed quantity affected by this adjustment. Negative values represent reductions (e.g. returns); positive values represent additions (e.g. exchanges). */ quantity: number; [k: string]: unknown; }>; /** - * Amount in minor units (cents) for refunds, credits, price adjustments (optional). + * Adjustment totals breakdown. Signed values—negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges). */ - amount?: number; + totals?: Total[]; /** * Human-readable reason or description (e.g., 'Defective item', 'Customer requested'). */ @@ -2028,12 +1791,22 @@ export declare interface Adjustment { * Platform's order capability configuration. * * This interface was referenced by `Order`'s JSON-Schema - * via the `definition` "platform_config". + * via the `definition` "platform_schema". */ -export declare interface PlatformOrderConfig { +export declare interface PlatformOrderSchema { /** * URL where merchant sends order lifecycle events (webhooks). */ webhook_url: string; [k: string]: unknown; } +/** + * Payment configuration containing handlers. + */ +export declare interface Payment1 { + /** + * 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. + */ + instruments?: SelectedPaymentInstrument[]; + [k: string]: unknown; +} \ No newline at end of file diff --git a/source/schemas/shopping/order.json b/source/schemas/shopping/order.json index 80fdd4cf..75ec1f66 100644 --- a/source/schemas/shopping/order.json +++ b/source/schemas/shopping/order.json @@ -3,7 +3,7 @@ "$id": "https://ucp.dev/schemas/shopping/order.json", "name": "dev.ucp.shopping.order", "title": "Order", - "description": "Order schema with immutable line items, buyer-facing fulfillment expectations, and append-only event logs.", + "description": "Order schema with line items, buyer-facing fulfillment expectations, and event logs.", "$defs": { "platform_schema": { "title": "Platform Order Schema", @@ -25,7 +25,7 @@ "required": [ "ucp", "id", - "checkout_id", + "checkouts", "permalink_url", "line_items", "fulfillment", @@ -39,9 +39,25 @@ "type": "string", "description": "Unique order identifier." }, - "checkout_id": { - "type": "string", - "description": "Associated checkout ID for reconciliation." + "checkouts": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["id", "created_at"], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the checkout session." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "RFC 3339 timestamp when this checkout session was created." + } + } + }, + "description": "Associated checkout sessions. Orders reference one or more checkouts—order edits and exchanges create additional checkout sessions against the same order." }, "permalink_url": { "type": "string", @@ -53,7 +69,7 @@ "items": { "$ref": "types/order_line_item.json" }, - "description": "Immutable line items — source of truth for what was ordered." + "description": "Line items representing what was purchased — can change post-order via edits or exchanges." }, "fulfillment": { "type": "object", @@ -80,7 +96,7 @@ "items": { "$ref": "types/adjustment.json" }, - "description": "Append-only event log of money movements (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment." + "description": "Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment." }, "currency": { "type": "string", diff --git a/source/schemas/shopping/types/adjustment.json b/source/schemas/shopping/types/adjustment.json index 2bfc7040..cf926a66 100644 --- a/source/schemas/shopping/types/adjustment.json +++ b/source/schemas/shopping/types/adjustment.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://ucp.dev/schemas/shopping/types/adjustment.json", "title": "Adjustment", - "description": "Append-only event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.", + "description": "Post-order event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.", "type": "object", "required": [ "id", @@ -45,16 +45,30 @@ }, "quantity": { "type": "integer", - "minimum": 1, - "description": "Quantity affected by this adjustment." + "description": "Signed quantity affected by this adjustment. Negative values represent reductions (e.g. returns); positive values represent additions (e.g. exchanges)." } } }, "description": "Which line items and quantities are affected (optional)." }, - "amount": { - "$ref": "amount.json", - "description": "Amount in ISO 4217 minor units for refunds, credits, or price adjustments." + "totals": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "total.json" + }, + { + "type": "object", + "properties": { + "amount": { + "$ref": "signed_amount.json" + } + } + } + ] + }, + "description": "Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges)." }, "description": { "type": "string", diff --git a/source/schemas/shopping/types/order_line_item.json b/source/schemas/shopping/types/order_line_item.json index 758e6b63..843e9839 100644 --- a/source/schemas/shopping/types/order_line_item.json +++ b/source/schemas/shopping/types/order_line_item.json @@ -23,18 +23,23 @@ "type": "object", "required": ["total", "fulfilled"], "properties": { + "original": { + "type": "integer", + "minimum": 0, + "description": "Quantity from the original checkout (earliest created_at). Convenience property—avoids requiring a separate Checkout lookup." + }, "total": { "type": "integer", "minimum": 0, - "description": "Current total quantity." + "description": "Current total quantity. May differ from original due to order edits or exchanges." }, "fulfilled": { "type": "integer", "minimum": 0, - "description": "Quantity fulfilled (sum from fulfillment events)." + "description": "Quantity fulfilled so far." } }, - "description": "Quantity tracking. Both total and fulfilled are derived from events." + "description": "Quantity tracking for the line item." }, "totals": { "type": "array", diff --git a/source/schemas/shopping/types/signed_amount.json b/source/schemas/shopping/types/signed_amount.json new file mode 100644 index 00000000..b68d5778 --- /dev/null +++ b/source/schemas/shopping/types/signed_amount.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://ucp.dev/schemas/shopping/types/signed_amount.json", + "title": "Signed Amount", + "description": "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).", + "type": "integer" +}