From a900c3108bcf5751d59472384993a77e091f6219 Mon Sep 17 00:00:00 2001
From: Daniel Kift <daniel.kift@shopify.com>
Date: Wed, 3 Jun 2026 18:11:18 +0100
Subject: [PATCH] fix ec.error shape in web platform

---
 platforms/web/src/checkout.test.ts  | 49 +++++++++++++++++++++++------
 platforms/web/src/checkout.ts       |  9 ++++--
 platforms/web/src/checkout.types.ts |  9 ++++--
 3 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/platforms/web/src/checkout.test.ts b/platforms/web/src/checkout.test.ts
index e392748e..7644e178 100644
--- a/platforms/web/src/checkout.test.ts
+++ b/platforms/web/src/checkout.test.ts
@@ -750,16 +750,39 @@ describe("<shopify-checkout>", () => {
         const onErrorSpy = vi.fn();
         const listenForEvent = waitForEvent(checkout, "checkout:error", onErrorSpy);
 
-        const errorPayload = makeErrorPayload({ severity: "recoverable" });
-        simulateProtocolMessageEvent(checkout, "ec.error", errorPayload, {
+        const errorParams = makeErrorParams({ severity: "recoverable" });
+        simulateProtocolMessageEvent(checkout, "ec.error", errorParams, {
           source: mockCheckoutWindow,
         });
         await listenForEvent;
 
-        expect(checkout.error).toStrictEqual(errorPayload);
+        expect(checkout.error).toStrictEqual(errorParams.error);
         expect(onErrorSpy).toHaveBeenCalledOnce();
       });
 
+      it("ignores the old ec.error shape with ucp and messages directly in params", async () => {
+        const { checkout, mockCheckoutWindow } = openPopupCheckout();
+        const onErrorSpy = vi.fn();
+        checkout.addEventListener("checkout:error", onErrorSpy);
+
+        const errorPayload = makeErrorPayload();
+        window.dispatchEvent(
+          new MessageEvent("message", {
+            data: {
+              jsonrpc: "2.0",
+              method: "ec.error",
+              params: errorPayload,
+            },
+            origin: new URL(checkout.src).origin,
+            source: mockCheckoutWindow,
+          }),
+        );
+        await Promise.resolve();
+
+        expect(checkout.error).toBeUndefined();
+        expect(onErrorSpy).not.toHaveBeenCalled();
+      });
+
       it("auto-closes when any message has severity 'unrecoverable'", async () => {
         const { checkout, mockCheckoutWindow } = openPopupCheckout();
         const errorOrder: string[] = [];
@@ -769,7 +792,7 @@ describe("<shopify-checkout>", () => {
         simulateProtocolMessageEvent(
           checkout,
           "ec.error",
-          makeErrorPayload({ severity: "unrecoverable" }),
+          makeErrorParams({ severity: "unrecoverable" }),
           { source: mockCheckoutWindow },
         );
         await Promise.resolve();
@@ -789,7 +812,7 @@ describe("<shopify-checkout>", () => {
           const closeSpy = vi.fn();
           checkout.addEventListener("checkout:close", closeSpy);
 
-          simulateProtocolMessageEvent(checkout, "ec.error", makeErrorPayload({ severity }), {
+          simulateProtocolMessageEvent(checkout, "ec.error", makeErrorParams({ severity }), {
             source: mockCheckoutWindow,
           });
           await Promise.resolve();
@@ -915,14 +938,14 @@ describe("<shopify-checkout>", () => {
         const spy = vi.fn();
         const wait = waitForEvent(checkout, "checkout:error", spy);
 
-        const errorPayload = makeErrorPayload();
-        simulateProtocolMessageEvent(checkout, "ec.error", errorPayload, {
+        const errorParams = makeErrorParams();
+        simulateProtocolMessageEvent(checkout, "ec.error", errorParams, {
           source: mockCheckoutWindow,
         });
         await wait;
 
         const event = spy.mock.calls[0]![0] as CustomEvent;
-        expect(event.detail).toEqual({ error: errorPayload });
+        expect(event.detail).toEqual({ error: errorParams.error });
       });
 
       it("checkout:lineItemsChange carries {lineItems, checkout}", async () => {
@@ -1498,7 +1521,7 @@ describe("<shopify-checkout>", () => {
 function simulateProtocolMessageEvent<Message extends keyof CheckoutProtocolMessageMap>(
   checkout: ShopifyCheckout,
   name: Message,
-  body: CheckoutProtocolMessageMap[Message],
+  params: CheckoutProtocolMessageMap[Message],
   options?: {
     id?: string;
     source?: MessageEventSource | null;
@@ -1520,7 +1543,7 @@ function simulateProtocolMessageEvent<Message extends keyof CheckoutProtocolMess
     data: {
       jsonrpc: "2.0",
       method: name,
-      params: body,
+      params,
       ...(options?.id && { id: options.id }),
     },
     origin,
@@ -1646,3 +1669,9 @@ function makeErrorPayload(overrides?: {
     ],
   };
 }
+
+function makeErrorParams(overrides?: {
+  severity?: CheckoutMessageError["severity"];
+}): CheckoutProtocolMessageMap["ec.error"] {
+  return { error: makeErrorPayload(overrides) };
+}
diff --git a/platforms/web/src/checkout.ts b/platforms/web/src/checkout.ts
index 4cf1e6ea..0159d2fa 100644
--- a/platforms/web/src/checkout.ts
+++ b/platforms/web/src/checkout.ts
@@ -553,7 +553,7 @@ export class ShopifyCheckout
         break;
       }
       case "ec.error": {
-        const error = message.body as CheckoutProtocolMessageMap["ec.error"];
+        const { error } = message.body as CheckoutProtocolMessageMap["ec.error"];
         this.#error = error;
         this.dispatchEvent(new ShopifyCheckoutErrorEvent({ error }));
         // Per UCP spec, `unrecoverable` means no valid resource exists to act on —
@@ -801,7 +801,7 @@ export interface ShopifyCheckoutCompleteEventDetail {
 }
 
 export interface ShopifyCheckoutErrorEventDetail {
-  /** Wire-shape error payload from the ECP `ec.error` notification. */
+  /** Error payload from the ECP `ec.error` notification. */
   error: UcpErrorResponse;
 }
 
@@ -924,6 +924,7 @@ class CheckoutProtocolMessage<
   static parse(event: MessageEvent): CheckoutProtocolMessage | undefined {
     const { data, source, origin } = event;
     if (!isCheckoutProtocolMessage(data)) return;
+    if (data.method === "ec.error" && !isEcErrorParams(data.params)) return;
     return new CheckoutProtocolMessage(data, { source, origin });
   }
 
@@ -950,6 +951,10 @@ class CheckoutProtocolMessage<
   }
 }
 
+function isEcErrorParams(params: unknown): params is CheckoutProtocolMessageMap["ec.error"] {
+  return params != null && typeof params === "object" && "error" in params;
+}
+
 function isCheckoutProtocolMessage(data: unknown): data is CheckoutProtocolMessageData {
   return (
     data != null &&
diff --git a/platforms/web/src/checkout.types.ts b/platforms/web/src/checkout.types.ts
index 8fca45c5..b70babdd 100644
--- a/platforms/web/src/checkout.types.ts
+++ b/platforms/web/src/checkout.types.ts
@@ -161,7 +161,7 @@ export interface CheckoutCloseEvent {
 export interface CheckoutErrorEvent {
   type: "checkout:error";
   detail: {
-    /** Wire-shape error payload from the ECP `ec.error` notification. */
+    /** Error payload from the ECP `ec.error` notification. */
     error: UcpErrorResponse;
   };
 }
@@ -236,6 +236,11 @@ interface CheckoutPayload {
   shop_cash?: ShopCash;
 }
 
+/** `ec.error` wraps the generated error response in the JSON-RPC `params.error` field. */
+export interface EcErrorParams {
+  error: UcpErrorResponse;
+}
+
 /**
  * Mapping of the 2026-04-08 ECP messages this component handles to their
  * wire-format payloads. Delegation methods (fulfillment.address_change_request,
@@ -247,7 +252,7 @@ export interface CheckoutProtocolMessageMap {
   "ec.ready": EcReadyParams;
   "ec.start": CheckoutPayload;
   "ec.complete": CheckoutPayload;
-  "ec.error": UcpErrorResponse;
+  "ec.error": EcErrorParams;
   "ec.line_items.change": CheckoutPayload;
   "ec.buyer.change": CheckoutPayload;
   "ec.totals.change": CheckoutPayload;