[Protocol] Adopt UCP 2026-08-25 across Checkout Kit by adrian-augustyn · Pull Request #794 · Shopify/checkout-kit

adrian-augustyn · 2026-09-18T19:05:27Z

What changes are you making?

Checkout-web already understands UCP August when a client asks for it. Before this change, Checkout Kit still asked for April and used models generated from the April specification. This PR updates the Checkout Kit side: Web, Swift, and Android request 2026-08-25, and their generated models understand the August response.

The change also keeps focused support for older April messages that Checkout Kit may still encounter. This is compatibility when reading JSON from checkout-web; it does not mean that every application using the generated models will compile unchanged. This PR does not publish packages or change released dependency versions.

Tracks shop/issues-checkout-kit#1237.
Uses the checkout-web support tracked in shop/issues-checkout-kit#1236.
Pins ucp@v2026-08-25, resolved to cd78fb38e819de77d9b527d110476eccb876f1bd.

What changed?

UCP schemas and generated models: update the pinned UCP copy to August, include all schemas it references, and regenerate the TypeScript, Swift, and Kotlin models from the resulting 99 files.
Version sent to checkout-web: Web, Swift, and Android send exactly one ec_version=2026-08-25 in the checkout URL. Checkout Kit replaces older or duplicate values already present in that URL.
Stable generated APIs: prepare temporary schema copies before running quicktype, leaving the upstream UCP files untouched. These adjustments keep intentional names such as Measure, ConstraintExpression, and ConstraintProperty. They also ensure Swift and Kotlin retain business-specific JSON fields where the protocol allows them. Generation stops with a clear error if an upstream change invalidates any of these assumptions.
TypeScript generation: remove quicktype's internal rename-map declaration only after verifying that no generated declaration still refers to it.
Legacy descriptions: accept the older April string form of FulfillmentOption.description and convert it to the current Description object with plain set. Encoding that value again produces { "plain": "…" }; it does not recreate the old string form.

The separate public-event redesign in #748 is not part of this change.

Compatibility and public API impact

Compatibility tests run the same example April and August checkout messages through TypeScript, Swift, and Kotlin. Those examples decode successfully. This does not prove that every historical message works, or that code using the generated models will compile without changes.

August examples decode the new map_order, structured descriptions, business-location destinations, and new fulfillment values such as drone_delivery.
Example April checkout and error messages still decode. April destinations can omit the type field added in August, and old description strings become Description.plain.
When the protocol allows a business to add its own fields, those unknown JSON fields survive decoding and re-encoding. Extra keys inside UCP metadata have a narrower guarantee: TypeScript preserves them, while Swift and Kotlin accept them but may not write them back.
Fulfillment method types change from a fixed list to strings, allowing businesses to add values beyond shipping and pickup. Code that directly uses the old enum cases or exhaustive switches must change.
FulfillmentOption.description changes from a string to the structured Description type.
Generated Swift initializers and Kotlin/Java constructors, copy functions, and component functions change where August adds fields.
Payment-instrument constraints use the clearer generated names ConstraintExpression and ConstraintProperty.

These source changes affect code that directly constructs or inspects the generated protocol models. Applications using only higher-level Checkout Kit APIs may be unaffected.

Swift and Kotlin protocol API reports were regenerated and reviewed. The Android Checkout Kit API, other Swift module reports, React Native API report, published native SDK pointers, and release coordinates remain unchanged.

How was this tested?

Local verification for this change includes:

all 99 schema files match the pinned UCP commit;
TypeScript, Swift, and Kotlin generation passes, and running generation a second time produces no further changes;
TypeScript protocol tests pass (70/70), Kotlin protocol tests pass (50/50), and Web tests pass (247/247);
the April checkout, August checkout, and April error examples pass in TypeScript, Swift, and Kotlin;
Swift and Android tests, public API checks, and lint pass;
protocol and Web lint pass; and
git diff --check passes.

The all-in-one dev protocol check reaches its standalone macOS Swift test, compiles successfully, and then exits without diagnostics because of a local test-runner problem. The same Swift compatibility and package suites pass through the simulator-backed runner.

Where should reviewers focus?

The temporary schema adjustments and safety checks in protocol/scripts/.
The Swift and Kotlin public API changes, especially the move from fulfillment enums to strings and the changed generated signatures.
The April/August examples and the specific older formats accepted for compatibility.
The boundary between unknown fields preserved through re-encoding and unknown UCP metadata that native models may drop.

The 99 pinned schema files are an upstream import rather than hand-written Checkout Kit code. dev protocol check-upstream verifies that they exactly match the selected UCP commit.

Merge requirements

Required GitHub and Bitrise checks and code-owner approval.
A deployed checkout-web flow must confirm that Checkout Kit requests 2026-08-25; rendering through the April fallback is not sufficient evidence.

Package publication and release coordination happen separately from this PR.

Supersedes #765, which contains the initial review discussion. The branch was moved into Shopify/checkout-kit so the repository's full CI can run.

Assisted-By: devx/9ecb7751-82f9-4062-885f-a23b95dfc4a7

github-actions · 2026-09-18T19:06:07Z

Protocol — Coverage Report

Lines	Statements	Branches	Functions
	93.75% (150/160)	88.67% (94/106)	90.32% (28/31)

github-actions · 2026-09-18T19:06:08Z

React Native — Coverage Report

Lines	Statements	Branches	Functions
	90.97% (363/399)	87.29% (213/244)	100% (92/92)

github-actions · 2026-09-18T19:06:08Z

Web — Coverage Report

Lines	Statements	Branches	Functions
	94.47% (342/362)	81.77% (166/203)	96.84% (92/95)

github-actions · 2026-09-18T19:09:03Z

Package Size

Platform	Artifact	Base	Head	Delta
Web	npm tarball	80.1 KiB	91.3 KiB	+11.2 KiB
React Native	npm tarball	108.6 KiB	119.0 KiB	+10.4 KiB
Android	release AAR	366.6 KiB	366.6 KiB	-8 B

Web file breakdown

File	Base	Head	Delta
`dist/index.js.map`	217.7 KiB	243.7 KiB	+26.0 KiB
`dist/index.d.ts`	45.9 KiB	64.3 KiB	+18.3 KiB
`dist/custom-elements.json`	51.4 KiB	51.4 KiB	0 B
`dist/index.js`	39.5 KiB	40.5 KiB	+985 B
`README.md`	20.0 KiB	20.0 KiB	+18 B
`package.json`	2.9 KiB	2.9 KiB	0 B
`LICENSE`	1.1 KiB	1.1 KiB	0 B

React Native file breakdown

File	Base	Head	Delta
`node_modules/@shopify/checkout-kit-protocol/src/generated/Models.ts`	85.4 KiB	108.7 KiB	+23.4 KiB
`node_modules/@shopify/checkout-kit-protocol/src/generated/Models.d.ts`	53.0 KiB	73.1 KiB	+20.1 KiB
`android/src/main/java/com/shopify/reactnative/checkoutkit/ShopifyCheckoutKitModule.java`	16.2 KiB	16.2 KiB	0 B
`ios/ShopifyCheckoutKit.swift`	16.1 KiB	16.1 KiB	0 B
`ios/AcceleratedCheckoutButtons.swift`	14.1 KiB	14.1 KiB	0 B
`src/components/AcceleratedCheckoutButtons.tsx`	13.0 KiB	13.0 KiB	0 B
`src/index.ts`	12.7 KiB	12.7 KiB	0 B
`lib/commonjs/index.js`	12.4 KiB	12.4 KiB	0 B
`lib/commonjs/components/AcceleratedCheckoutButtons.js`	11.4 KiB	11.4 KiB	0 B
`src/index.d.ts`	11.3 KiB	11.3 KiB	0 B
`lib/commonjs/components/AcceleratedCheckoutButtons.js.map`	10.4 KiB	10.4 KiB	0 B
`lib/module/index.js`	10.4 KiB	10.4 KiB	0 B
`lib/module/components/AcceleratedCheckoutButtons.js`	10.2 KiB	10.2 KiB	0 B
`node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolNotifications.ts`	9.5 KiB	9.5 KiB	0 B
`lib/module/components/AcceleratedCheckoutButtons.js.map`	9.1 KiB	9.1 KiB	0 B
`lib/module/index.js.map`	8.1 KiB	8.1 KiB	0 B
`src/present-dispatcher.ts`	8.0 KiB	8.0 KiB	0 B
`lib/commonjs/index.js.map`	7.9 KiB	7.9 KiB	0 B
`node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolRenameMap.ts`	7.2 KiB	7.8 KiB	+606 B
`node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolNotifications.d.ts`	7.6 KiB	7.6 KiB	0 B
…and 117 smaller files

Android file breakdown

File	Base	Head	Delta
`classes.jar`	390.5 KiB	390.5 KiB	+1 B
`res/layout/checkout_view_content.xml`	2.6 KiB	2.6 KiB	0 B
`res/layout/checkout_sheet_content.xml`	2.0 KiB	2.0 KiB	0 B
`res/values/values.xml`	1.3 KiB	1.3 KiB	0 B
`R.txt`	1.2 KiB	1.2 KiB	0 B
`AndroidManifest.xml`	922 B	922 B	0 B
`proguard.txt`	798 B	798 B	0 B
`res/drawable/close.xml`	431 B	431 B	0 B
`res/menu/checkout_menu.xml`	354 B	354 B	0 B
`META-INF/com/android/build/gradle/aar-metadata.properties`	157 B	157 B	0 B

Measured from the PR base SHA and PR head SHA. The file breakdown shows uncompressed sizes within each package artifact, so individual files do not sum to the compressed artifact total. This comment reports package artifact sizes only; it is not a final app binary-size report.

bitrise · 2026-09-18T19:28:50Z

Install this build

Open Tophat, select your target device, then click Install. Links open on the Mac running Tophat.

SDK	Install
React Native	Install with Tophat
Swift	Install with Tophat
Kotlin	Install with Tophat

Checkout Kit E2E results

Status	Tags	Target	Platform	OS version tag	Device
✅	`launch, checkout-presentation, checkout-completion, buyer-identity`	react-native	ios	latest	iPhone 15 iOS 27 Beta
✅	`launch, checkout-presentation, checkout-completion, buyer-identity`	react-native	android	latest	Google Pixel 9 Android 17.0
✅	`launch, checkout-presentation, checkout-completion, buyer-identity, preload`	kotlin	android	latest	Google Pixel 9 Android 17.0
✅	`launch, checkout-presentation, checkout-completion, buyer-identity, preload`	swift	ios	latest	iPhone 15 iOS 27 Beta

markmur

First pass

markmur · 2026-09-24T08:23:21Z

    it("replaces caller-supplied ec_* parameters", () => {
      const checkout = renderCheckout({
-        src: "https://example.com/checkout?ec_version=stale&ec_delegate=custom",
+        src: "https://example.com/checkout?ec_version=2026-04-08&ec_version=stale&ec_delegate=custom",


This looks a bit weird. We don't need two instances of ec_version in the URL for this test

markmur · 2026-09-24T08:23:30Z


      const url = new URL(expectWindowOpenArgs(windowOpenSpy)[0] as string);
-      expect(url.searchParams.getAll("ec_version")).toEqual([EMBED_PROTOCOL_VERSION]);
+      expect(url.searchParams.getAll("ec_version")).toEqual(["2026-08-25"]);


The variable was arguably better here

markmur · 2026-09-24T08:24:30Z

        let twice = CheckoutURLDecorator.decorate(once, configuration: configuration)
        let items = queryItems(twice)

+        #expect(items.filter { $0.name == "ec_version" }.map(\.value) == ["2026-08-25"])


Can we read this from the protocol lib directly? One less thing to update when we upgrade next time

markmur · 2026-09-24T08:24:48Z

        configuration.appearance = .app(.light)

-        let url = try #require(URL(string: "https://shop.com/cart/c/abc?ck_branding=app&ec_color_scheme=dark"))
+        let url = try #require(URL(string: "https://shop.com/cart/c/abc?ec_version=2026-04-08&ec_version=stale&ck_branding=app&ec_color_scheme=dark"))


We don't need two instances of ec_version here either

markmur · 2026-09-24T08:25:46Z

@@ -1,3 +1,4 @@
+// April wire payloads are retained here as older-version compatibility coverage.


This sound wrong;

We can drop the comment

Test coverage should cover the pinned version holistically

markmur · 2026-09-24T08:29:48Z


    @Test
-    fun `checkout model decodes extension fields`() {
+    fun `April checkout model decodes extension fields`() {


We can drop references to "April model" everywhere

markmur · 2026-09-24T08:30:19Z

    @Test
    fun `decorate replaces caller-supplied supported ECP params and strips unsupported ECP params`() {
-        val url = "$BASE_URL?ec_version=override&ec_delegate=custom&ec_auth=token&ec_color_scheme=dark&ck_branding=app"
+        val url = "$BASE_URL?ec_version=2026-04-08&ec_version=stale&ec_delegate=custom&ec_auth=token&ec_color_scheme=dark&ck_branding=app"


Drop duplicative params here

markmur · 2026-09-24T08:30:25Z

+        val url = "$BASE_URL?ec_version=2026-04-08&ec_version=stale&ec_delegate=custom&ec_auth=token&ec_color_scheme=dark&ck_branding=app"
        val result = CheckoutUrlDecorator.decorate(url).toUri()
-        assertThat(result.getQueryParameters("ec_version")).containsExactly(CheckoutProtocol.SPEC_VERSION)
+        assertThat(result.getQueryParameters("ec_version")).containsExactly("2026-08-25")


Pinned static version here was better

markmur · 2026-09-24T08:32:21Z

 import org.assertj.core.api.Assertions.assertThat
 import org.junit.Test

+// April wire payloads are retained here as older-version compatibility coverage.


We can drop this comment

feat(protocol): adopt UCP 2026-08-25

d837ca8

Assisted-By: devx/9ecb7751-82f9-4062-885f-a23b95dfc4a7

adrian-augustyn requested a review from a team as a code owner September 18, 2026 19:05

github-actions Bot added the #gsd:50662 Rebase Checkout Kit on UCP label Sep 18, 2026

adrian-augustyn mentioned this pull request Sep 18, 2026

[Protocol] Adopt UCP 2026-08-25 across Checkout Kit #765

Closed

markmur reviewed Sep 24, 2026

View reviewed changes

		@@ -1,3 +1,4 @@
		// April wire payloads are retained here as older-version compatibility coverage.

Conversation

adrian-augustyn commented Sep 18, 2026

What changes are you making?

What changed?

Compatibility and public API impact

How was this tested?

Where should reviewers focus?

Merge requirements

Uh oh!

github-actions Bot commented Sep 18, 2026

Protocol — Coverage Report

Uh oh!

github-actions Bot commented Sep 18, 2026

React Native — Coverage Report

Uh oh!

github-actions Bot commented Sep 18, 2026

Web — Coverage Report

Uh oh!

github-actions Bot commented Sep 18, 2026

Package Size

Uh oh!

bitrise Bot commented Sep 18, 2026

Install this build

Checkout Kit E2E results

Uh oh!

markmur left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants