Add checkout kit web component ck_version query param

platforms/web/src/checkout.test.ts

@@ -2,7 +2,12 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { Checkout, CheckoutProtocolMessageMap, UcpErrorResponse } from "./checkout.types";
 import "./checkout-web-component";
-import { DEFAULT_POPUP_WIDTH, DEFAULT_POPUP_HEIGHT, EMBED_PROTOCOL_VERSION } from "./checkout";
+import {
+  DEFAULT_POPUP_WIDTH,
+  DEFAULT_POPUP_HEIGHT,
+  EMBED_PROTOCOL_VERSION,
+  CK_VERSION,
+} from "./checkout";
 import type { ShopifyCheckout } from "./checkout";
 
 const POPUP_TARGETS = ["popup"] as const;
@@ -826,6 +831,43 @@ describe("<shopify-checkout>", () => {
     });
   });
 
+  describe("ck_version parameter", () => {
+    it("appends ck_version to the opened URL", () => {
+      const checkout = renderCheckout({ target: "popup" });
+
+      const windowOpenSpy = vi.spyOn(window, "open").mockReturnValue(createMockWindow());
+
+      checkout.open();
+
+      const url = new URL(expectWindowOpenArgs(windowOpenSpy)[0] as string);
+      expect(url.searchParams.get("ck_version")).toBe(CK_VERSION);
+    });
+
+    it("uses the documented constant value", () => {
+      expect(CK_VERSION).toBe("4.0.0");
+    });
+
+    it("includes ck_version on the overlay link", () => {
+      const checkout = renderCheckout({ src: "https://shop.example.com/checkout" });
+      const link = checkout.shadowRoot!.querySelector<HTMLAnchorElement>("#overlay-link");
+      const url = new URL(link!.getAttribute("href") ?? "");
+      expect(url.searchParams.get("ck_version")).toBe(CK_VERSION);
+    });
+
+    it("preserves caller-provided ck_version rather than appending a duplicate", () => {
+      const checkout = renderCheckout({
+        src: "https://shop.example.com/checkout?ck_version=old",
+      });
+
+      const windowOpenSpy = vi.spyOn(window, "open").mockReturnValue(createMockWindow());
+
+      checkout.open();
+
+      const url = new URL(expectWindowOpenArgs(windowOpenSpy)[0] as string);
+      expect(url.searchParams.getAll("ck_version")).toEqual([CK_VERSION]);
+    });
+  });
+
   describe("debug attribute", () => {
     it("logs a console warning for dropped messages when the debug attribute is set", async () => {
       const { checkout, mockCheckoutWindow } = openPopupCheckout();

platforms/web/src/checkout.ts

@@ -38,6 +38,7 @@ import { STYLES } from "./checkout.styles";
 export const DEFAULT_POPUP_WIDTH = 600;
 export const DEFAULT_POPUP_HEIGHT = 600;
 export const EMBED_PROTOCOL_VERSION = "2026-04-08";
+export const CK_VERSION = "4.0.0";
 const EMBED_DELEGATIONS: readonly string[] = ["window.open"];
 
 const SHADOW_TEMPLATE = createTemplate(html`
@@ -157,6 +158,7 @@ export class ShopifyCheckout
     if (EMBED_DELEGATIONS.length > 0) {
       url.searchParams.set("ec_delegate", EMBED_DELEGATIONS.join(","));
     }
+    url.searchParams.set("ck_version", CK_VERSION);
     return url;
   }