diff --git a/docs/specification/embedded-cart.md b/docs/specification/embedded-cart.md index 8ed212e6..2c68a488 100644 --- a/docs/specification/embedded-cart.md +++ b/docs/specification/embedded-cart.md @@ -361,6 +361,8 @@ proceed to initiate a checkout session based on the completed cart by issuing a - **Type:** Notification - **Payload:** - `cart` (object, **REQUIRED**): The final state of the cart. + - `transition` (object, **OPTIONAL**): Advertisement for availability to transition + directly into Embedded Checkout. **Example Message:** @@ -381,6 +383,59 @@ proceed to initiate a checkout session based on the completed cart by issuing a } ``` +Business **MAY** also choose to specify a `transition` field to advertise a mechanism +for hosts to seamlessly transition into Embedded Checkout from the completed +Embedded Cart. This is represented by `transition` containing a minimal `checkout` object: + +- `ucp` (object, **REQUIRED**): Metadata to fully qualify the advertisement. + Business **MUST** include a checkout capability and an embedded service binding + with `config.delegate`. +- `url` (string, **REQUIRED**): URL representing shift to checkout. Business **MUST** + specify a HTTPS URL and **MAY** choose a stateless URL like permalink. See + [Checkout Capability - Continue URL Format](checkout.md#format). + +**Example Message With `transition`:** + +```json +{ + "jsonrpc": "2.0", + "method": "ep.cart.complete", + "params": { + "cart": { ...cart fields... }, + "transition": { + "checkout": { + "ucp": { + "version": "{{ ucp_version }}", + "status": "success", + "capabilities": { + "dev.ucp.shopping.checkout": [ { "version": "{{ ucp_version }}" } ] + }, + "services": { + "dev.ucp.shopping": [ + { + "version": "{{ ucp_version }}", + "transport": "embedded", + "config": { + "delegate": [...] + } + } + ] + } + }, + "url": "https://merchant.example.com/cart-to-checkout/checkout123", + } + } + } +} +``` + +When `transition` is received as part of `ep.cart.complete`, the host **MAY** choose +to initiate Embedded Checkout by appending `checkout.url` with relevant parameters - +see [Embedded Checkout - Loading an Embedded Checkout URL](embedded-checkout.md#loading-an-embedded-checkout-url). +Host also has full flexibility over how they want to render Embedded Checkout (i.e. +reuse the same embedded context as Embedded Cart or tear down the current one in favour +of bootstrapping a new embedded context). + ### State Change Messages State change notifications follow the shared EP pattern — see diff --git a/docs/specification/embedded-checkout.md b/docs/specification/embedded-checkout.md index e580f95e..6196637f 100644 --- a/docs/specification/embedded-checkout.md +++ b/docs/specification/embedded-checkout.md @@ -131,10 +131,11 @@ indicate ECP availability and allowed delegations for a specific session. ```json { "id": "checkout_abc123", - "status": "open", + "status": "incomplete", "continue_url": "https://merchant.example.com/checkout/abc123", "ucp": { "version": "{{ ucp_version }}", + "status": "success", "services": { "dev.ucp.shopping": [ { diff --git a/source/services/shopping/embedded.openrpc.json b/source/services/shopping/embedded.openrpc.json index 4210fea0..cfcefae8 100644 --- a/source/services/shopping/embedded.openrpc.json +++ b/source/services/shopping/embedded.openrpc.json @@ -496,6 +496,29 @@ "$ref": "../../schemas/shopping/cart.json", "description": "Final cart state." } + }, + { + "name": "transition", + "schema": { + "type": "object", + "description": "Optional advertisement from business for seamless transition from cart to checkout.", + "required": ["checkout"], + "properties": { + "checkout": { + "type": "object", + "description": "Metadata required by the host to bootstrap and transition into an embedded checkout session.", + "required": ["ucp", "url"], + "properties": { + "ucp": { "$ref": "#/components/schemas/ucp_success" }, + "url": { + "type": "string", + "format": "uri", + "description": "The transition URL." + } + } + } + } + } } ] },