Add checkout.directory UCP merchant import and executable-checkout eligibility pipeline

[seichris]

Summary

We should add an import/classification pipeline for UCP merchants from checkout.directory, then promote only the merchants that are actually executable on Fast Marketplace.

This issue is about:

1. ingesting current UCP checkout-capable merchants
2. storing their manifest/capability/payment-handler metadata
3. classifying which ones are only discovery-ready vs executable-ready
4. wiring the next-step executor work for payment-handler support and checkout/order/fulfillment mapping

Why

We currently have discovery and some marketplace execution primitives, but “adding a UCP merchant” is not enough to make purchases work.

To make a merchant actually purchasable on Fast Marketplace, we need:

• manifest ingestion
• checkout capability verification
• payment handler compatibility
• quote/consent/order/fulfillment mapping
• promotion rules from discovery-only to executable

checkout.directory is the right source for the merchant list because it exposes merchant metadata, capabilities, payment handlers, and manifests.

Current checkout.directory UCP merchants with checkout

As of 2026-04-17, checkout.directory returns these UCP merchants with checkout capability.

Source:

• checkout.directory
• API used: GET https://checkout.directory/api/merchants?protocol=UCP&limit=100

All merchants below currently advertise:

• dev.ucp.shopping.checkout
• dev.ucp.shopping.fulfillment

Merchants and payment handlers

Merchant	Domain	Payment Handlers
Monos	monos.com	com.google.pay, dev.shopify.card
Gymshark	gymshark.com	com.google.pay, dev.shopify.card
KEEN	keenfootwear.com	com.google.pay, dev.shopify.card
Pura Vida	puravidabracelets.com	com.google.pay, dev.shopify.card
Everlane	everlane.com	com.google.pay, dev.shopify.card
Kyte Baby	kytebaby.com	com.google.pay, dev.shopify.card
Allbirds	allbirds.com	com.google.pay, dev.shopify.card
Fashion Nova	fashionnova.com	com.google.pay, dev.shopify.card
Kylie Cosmetics	kyliecosmetics.com	com.google.pay, dev.shopify.card
Jeffree Star Cosmetics	jeffreestarcosmetics.com	com.google.pay, dev.shopify.card
Steve Madden	stevemadden.com	com.google.pay, dev.shopify.card
Glossier	glossier.com	com.google.pay, dev.shopify.card
Alo Yoga	aloyoga.com	com.google.pay, dev.shopify.card
Fender	fender.com	com.google.pay, dev.shopify.card
Raycon	rayconglobal.com	com.google.pay, dev.shopify.card
Chubbies	chubbiesshorts.com	com.google.pay, dev.shopify.card
Brooklinen	brooklinen.com	com.google.pay, dev.shopify.card
Away	awaytravel.com	com.google.pay, dev.shopify.card
Outdoor Voices	outdoorvoices.com	com.google.pay, dev.shopify.card
Casper	casper.com	com.google.pay, dev.shopify.card
Dollar Shave Club	dollarshaveclub.com	com.google.pay, dev.shopify.card
Boll & Branch	bollandbranch.com	com.google.pay, dev.shopify.card
Pier 1	pier1.com	com.google.pay, dev.shopify.card
UNTUCKit	untuckit.com	com.google.pay, dev.shopify.card
Nothing	nothing.tech	com.google.pay, dev.shopify.card
Fenty Beauty	fentybeauty.com	com.google.pay, dev.shopify.card
Rip Curl	ripcurl.com	com.google.pay, dev.shopify.card
Quiksilver	quiksilver.com	com.google.pay, dev.shopify.card
Billabong	billabong.com	com.google.pay, dev.shopify.card
Kelty	kelty.com	com.google.pay, dev.shopify.card
Stanley (Stately Men)	statelymen.com	com.google.pay, dev.shopify.card
Forever 21	forever21.com	com.google.pay, dev.shopify.card
Mejuri	mejuri.com	com.google.pay, dev.shopify.card
Harry's	harrys.com	com.google.pay, dev.shopify.card
Olaplex	olaplex.com	com.google.pay, dev.shopify.card
Moroccanoil	moroccanoil.com	com.google.pay, dev.shopify.card
Native	nativecos.com	com.google.pay, dev.shopify.card
Peach & Lily	peachandlily.com	com.google.pay, dev.shopify.card
The Body Shop	thebodyshop.com	com.google.pay, dev.shopify.card
Tuft & Needle	tuftandneedle.com	com.google.pay, dev.shopify.card
Public Goods	publicgoods.com	com.google.pay, dev.shopify.card
SKIMS	skims.com	com.google.pay, dev.shopify.card
Rothy's	rothys.com	com.google.pay, dev.shopify.card
Soko Glam	sokoglam.com	com.google.pay, dev.shopify.card
Burrow	burrow.com	com.google.pay, dev.shopify.card
Decathlon	decathlon.com	com.google.pay, dev.shopify.card
Tonal	tonal.com	com.google.pay, dev.shopify.card
Mattel	mattel.com	com.google.pay, dev.shopify.card
Primary	primary.com	com.google.pay, dev.shopify.card
Grove Collaborative	grove.co	com.google.pay, dev.shopify.card
ColourPop	colourpop.com	com.google.pay, dev.shopify.card

Implication

Right now, the limiting factor is not merchant discovery. It is payment-handler compatibility.

Based on the current directory data, these merchants appear to rely on:

• com.google.pay
• dev.shopify.card

So none of these should be promoted to executable on Fast Marketplace until we support an appropriate bridge for those payment handlers, or until a merchant advertises a Fast-compatible payment handler.

Scope

1. Add checkout.directory importer

• fetch merchant list from checkout.directory
• store merchant metadata locally
• fetch merchant manifest for selected merchants
• persist:
  • domain
  • capabilities
  • payment handlers
  • manifest/spec URLs
  • transport type/endpoints

2. Add merchant classifier

Classify imported merchants into:

• discovery_only
• checkout_capable
• executable_ready

Suggested rules:

• discovery_only

  • valid merchant entry exists

• checkout_capable

  • has dev.ucp.shopping.checkout

• executable_ready

  • has checkout
  • has fulfillment/order support
  • manifest fetch succeeds
  • usable transport endpoint exists
  • supported payment handler exists
  • quote/consent/order/fulfillment mapping is implemented

3. Keep imported merchants discovery-only by default

Do not promote imported UCP merchants directly to executable routes.

4. Add payment-handler compatibility matrix

We need a shared compatibility decision for:

• com.google.pay
• dev.shopify.card
• future ACP/AP2 providers such as:
  • Stripe
  • Worldpay
  • PayPal
  • Instacart

5. Add follow-up execution work only after compatibility exists

For any merchant promoted to executable, wire:

• quote persistence
• buyer consent
• order creation
• fulfillment updates
• refund/failure behavior
• payment bridging

Acceptance Criteria

• importer can fetch the current UCP merchant list from checkout.directory
• importer persists merchant capabilities and payment handlers
• importer can fetch and store merchant manifest metadata
• classifier marks all current merchants as at least checkout_capable
• executable promotion remains blocked unless supported payment handlers are available
• no merchant is exposed as executable checkout without manifest + payment-handler compatibility + commerce record mapping

Follow-ups

• issue: add checkout.directory import command / operator flow
• issue: add merchant manifest persistence in shared store
• issue: implement payment-handler compatibility matrix
• issue: support Google Pay / Shopify card bridge or equivalent wrapper path
• issue: promote first executable UCP merchant only after full quote/consent/order/fulfillment support is confirmed