{
  "openrpc": "1.3.2",
  "info": {
    "title": "UCP Shopping Embedded Protocol",
    "description": "Embedded Protocol (EP) methods for the UCP shopping service. Methods are sent from Merchant to Host via postMessage using JSON-RPC 2.0. Method prefixes indicate capability scope: ep.{capability} (i.e. ep.checkout). Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\nEmbedded Protocol is a client-to-client postMessage interface, so there is no endpoint URL to access this API. Platforms detect merchant support for this protocol based on the presence of `services[\"dev.ucp.shopping\"][transport=embedded]` in discovery responses."
  },
  "servers": [],
  "methods": [
    {
      "name": "ec.ready",
      "summary": "Handshake from merchant to host",
      "description": "Initiates the Embedded Checkout Protocol. Merchant declares which delegations it accepts and requests any additional authorization, host responds with optional channel upgrade, auth credential, and initial checkout state.",
      "params": [
        {
          "name": "delegate",
          "required": true,
          "schema": {
            "type": "array",
            "description": "Delegation types the merchant accepts. Must be subset of checkout.embedded.delegations.",
            "items": {
              "type": "string",
              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
            },
            "uniqueItems": true
          }
        },
        {
          "name": "auth",
          "schema": { "$ref": "#/components/schemas/auth" }
        }
      ],
      "result": {
        "name": "readyResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Handshake response from host.",
              "required": ["ucp"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "upgrade": {
                  "type": "object",
                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
                  "properties": {
                    "port": {
                      "type": "object",
                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
                    }
                  }
                },
                "credential": {
                  "type": "string",
                  "description": "Requested authorization. Some common examples include API key and OAuth token."
                },
                "checkout": {
                  "type": "object",
                  "description": "Initial delegation state from host. Fields are permitted only when the corresponding delegation is accepted.",
                  "properties": {
                    "payment": {
                      "$ref": "#/components/schemas/payment_instrument_selection"
                    },
                    "fulfillment": {
                      "$ref": "../../schemas/shopping/types/fulfillment.json"
                    }
                  }
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ec.auth",
      "summary": "Authorization exchange between host & business.",
      "description": "Augments Embedded Checkout Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
      "params": [
        {
          "name": "type",
          "schema": {"$ref": "#/components/schemas/type"}
        }
      ],
      "result": {
        "name": "authResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Auth response from host containing the requested authorization data.",
              "required": ["ucp", "credential"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "credential": {
                  "type": "string",
                  "description": "Requested authorization. Some common examples include API key and OAuth token."
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ec.error",
      "summary": "A session-level error has occurred.",
      "description": "Business notifies host that a session-level error, unrelated to the checkout resource, has occurred.",
      "params": [
        {
          "name": "error",
          "required": true,
          "schema": {
            "$ref": "../../schemas/common/types/error_response.json",
            "description": "Session-level error raised by the business."
          }
        }
      ]
    },

    {
      "name": "ec.start",
      "summary": "Checkout visible to buyer",
      "description": "Merchant notifies host that checkout UI is visible and ready for interaction. Sent after successful ec.ready handshake.",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state."
          }
        }
      ]
    },

    {
      "name": "ec.complete",
      "summary": "Checkout completed successfully",
      "description": "Merchant notifies host that order has been placed successfully.",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Final checkout state."
          }
        }
      ]
    },

    {
      "name": "ec.messages.change",
      "summary": "Checkout messages changed",
      "description": "Merchant notifies host that checkout.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with updated messages."
          }
        }
      ]
    },

    {
      "name": "ec.line_items.change",
      "summary": "Line items changed",
      "description": "Merchant notifies host that checkout.line_items has changed (item added, removed, quantity updated).",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with updated line items."
          }
        }
      ]
    },

    {
      "name": "ec.buyer.change",
      "summary": "Buyer information changed",
      "description": "Merchant notifies host that checkout.buyer has changed (email, phone, address updated).",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with updated buyer."
          }
        }
      ]
    },

    {
      "name": "ec.totals.change",
      "summary": "Checkout totals changed",
      "description": "Merchant notifies host that checkout.totals has changed. Covers all total line updates including taxes, fees, discounts, and fulfillment costs. For changes that also affect a specific domain (e.g., fulfillment cost update), this message MUST be sent after the domain-specific change message (e.g., ec.fulfillment.change).",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with updated totals."
          }
        }
      ]
    },

    {
      "name": "ec.payment.change",
      "summary": "Payment state changed",
      "description": "Merchant notifies host that checkout.payment has changed (instrument selected, status updated).",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with updated payment."
          }
        }
      ]
    },

    {
      "name": "ec.payment.instruments_change_request",
      "summary": "Request payment instrument change",
      "description": "Merchant requests host to present payment instrument selection UI for the buyer to change their payment method.",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state."
          }
        }
      ],
      "result": {
        "name": "instrumentsChangeResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Checkout state after instrument selection.",
              "required": ["ucp", "checkout"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "checkout": {
                  "type": "object",
                  "description": "Partial checkout update with payment instrument selection.",
                  "properties": {
                    "payment": {
                      "$ref": "#/components/schemas/payment_instrument_selection"
                    }
                  }
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ec.payment.credential_request",
      "summary": "Request payment credential",
      "description": "Merchant requests host to collect payment credential for selected instrument (CVV, 3DS, wallet confirmation).",
      "params": [
        {
          "name": "checkout",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/checkout.json",
            "description": "Current checkout state with selected instrument."
          }
        }
      ],
      "result": {
        "name": "credentialResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Checkout state with payment credential ready for completion.",
              "required": ["ucp", "checkout"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "checkout": {
                  "type": "object",
                  "description": "Partial checkout update with payment credential.",
                  "properties": {
                    "payment": {
                      "$ref": "#/components/schemas/payment_instruments"
                    }
                  }
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ec.window.open_request",
      "summary": "Request window open",
      "description": "The buyer activated a link within checkout. The host MUST present the content to the buyer and respond with a success result, or respond with a window_open_rejected_error error if host policy prevented the navigation.",
      "params": [
        {
          "name": "url",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the resource to present."
          }
        }
      ],
      "result": {
        "name": "windowOpenResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Acknowledgement that the host handled the request.",
              "required": ["ucp"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    { "$ref": "../../schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.change" },
    { "$ref": "../../schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.address_change_request" },

    {
      "name": "ep.cart.ready",
      "summary": "Handshake from business to host",
      "description": "Initiates the Embedded Cart Protocol. Business declares which delegation it supports and requests any additional authorization, host responds with optional channel upgrade and auth credential.",
      "params": [
        {
          "name": "delegate",
          "required": true,
          "schema": {
            "type": "array",
            "description": "Delegation types the merchant accepts.",
            "items": {
              "type": "string",
              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
            },
            "uniqueItems": true
          }
        },
        {
          "name": "auth",
          "schema": {"$ref": "#/components/schemas/auth"}
        }
      ],
      "result": {
        "name": "readyResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Handshake response from host.",
              "required": ["ucp"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "upgrade": {
                  "type": "object",
                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
                  "properties": {
                    "port": {
                      "type": "object",
                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
                    }
                  }
                },
                "credential": {
                  "type": "string",
                  "description": "Requested authorization. Some common examples include API key and OAuth token."
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ep.cart.auth",
      "summary": "Authorization exchange between host & business.",
      "description": "Augments Embedded Cart Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
      "params": [
        {
          "name": "type",
          "schema": {"$ref": "#/components/schemas/type"}
        }
      ],
      "result": {
        "name": "authResult",
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "description": "Auth response from host containing the requested authorization data.",
              "required": ["ucp", "credential"],
              "properties": {
                "ucp": { "$ref": "#/components/schemas/ucp_success" },
                "credential": {
                  "type": "string",
                  "description": "Requested authorization. Some common examples include API key and OAuth token."
                }
              }
            },
            {
              "$ref": "../../schemas/common/types/error_response.json"
            }
          ]
        }
      }
    },

    {
      "name": "ep.cart.error",
      "summary": "A session-level error has occurred.",
      "description": "Business notifies host that a session-level error, unrelated to the cart resource, has occurred.",
      "params": [
        {
          "name": "error",
          "required": true,
          "schema": {
            "$ref": "../../schemas/common/types/error_response.json",
            "description": "Session-level error raised by the business."
          }
        }
      ]
    },

    {
      "name": "ep.cart.start",
      "summary": "Cart visible to buyer",
      "description": "Business notifies host that cart UI is visible and ready for interaction.",
      "params": [
        {
          "name": "cart",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/cart.json",
            "description": "Current cart state."
          }
        }
      ]
    },

    {
      "name": "ep.cart.complete",
      "summary": "Cart completed successfully",
      "description": "Business notifies host that cart building has completed.",
      "params": [
        {
          "name": "cart",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/cart.json",
            "description": "Final cart state."
          }
        }
      ]
    },

    {
      "name": "ep.cart.line_items.change",
      "summary": "Line items changed",
      "description": "Business notifies host that cart.line_items has changed (item added, removed, quantity updated).",
      "params": [
        {
          "name": "cart",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/cart.json",
            "description": "Current cart state with updated line items."
          }
        }
      ]
    },

    {
      "name": "ep.cart.buyer.change",
      "summary": "Buyer information changed",
      "description": "Business notifies host that cart.buyer has changed (email, phone, name updated).",
      "params": [
        {
          "name": "cart",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/cart.json",
            "description": "Current cart state with updated buyer."
          }
        }
      ]
    },

    {
      "name": "ep.cart.messages.change",
      "summary": "Cart messages changed",
      "description": "Business notifies host that cart.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
      "params": [
        {
          "name": "cart",
          "required": true,
          "schema": {
            "$ref": "../../schemas/shopping/cart.json",
            "description": "Current cart state with updated messages."
          }
        }
      ]
    }
  ],
  "components": {
    "schemas": {
      "ucp_success": {
        "$ref": "../../schemas/ucp.json#/$defs/success"
      },
      "payment_instruments": {
        "type": "object",
        "description": "Payment instruments from host.",
        "properties": {
          "instruments": {
            "type": "array",
            "items": {
              "$ref": "../../schemas/shopping/types/payment_instrument.json#/$defs/selected_payment_instrument"
            },
            "description": "Available payment instruments."
          }
        }
      },
      "payment_instrument_selection": {
        "description": "Payment instruments with selected instrument ID.",
        "allOf": [
          { "$ref": "#/components/schemas/payment_instruments" },
          {
            "properties": {
              "selected_instrument_id": {
                "type": "string",
                "description": "ID of the selected payment instrument."
              }
            }
          }
        ]
      },
      "type": {
        "type": "string",
        "description": "The type of authorization data business is requesting from the host.",
        "examples": [
          "oauth",
          "api_key",
          "jwt"
        ]
      },
      "auth": {
        "type": "object",
        "properties": {
          "type": { "$ref": "#/components/schemas/type" }
        }
      }
    }
  },
  "x-delegations": ["payment.instruments_change", "payment.credential", "fulfillment.address_change", "window.open"]
}