feat: shopping permalink capability

[igrigorik]

Permalinks are a popular, well-established way to turn a single shareable URL into a pre-loaded cart or checkout. The link encodes the items — and often a discount, a destination, and some buyer prefill — directly, so a buyer taps it and lands at checkout with the right state already in place. They show up all across the funnel: email and SMS campaigns, social and influencer links, paid ads and landing pages, QR codes on print and packaging, "buy now" and share-cart buttons, bundle offers, etc. The whole point is friction reduction — replace "browse, find, add, configure" with one tap.

Most commerce platforms already offer some flavor of cart or checkout permalink, but each is platform-specific by construction: a proprietary origin, a platform-specific item-ID scheme, and a bespoke prefill vocabulary. A common shape is a cart permalink like /cart/{item_id}:{quantity} with a ?discount= parameter and platform-specific prefill fields. There is no cross-merchant, agent-addressable, schema-typed equivalent — nothing an AI agent, marketplace, or campaign tool can construct once and point at any UCP business.

This capability (dev.ucp.shopping.permalink) generalizes the permalink pattern into the protocol. It keeps the ergonomics — compact item path, a discount, a destination — but expresses prefill as typed UCP field paths resolved against the business's own Cart/Checkout schema, and replaces platform-specific behavior with a single redirect contract.

Design

The capability leans on existing UCP schemas, in a future-proof way.

It defines one control parameter, continue_to, and zero shopping-state fields of its own. Every data-carrying query parameter is an existing UCP field path written as a JSON Pointer with the leading / omitted — buyer/email, context/postal_code, discounts/codes/0, line_items/0/quantity — resolved against the business's Cart or Checkout schema.

The payment-handler preference is modeled as a new core context.payment_handlers field — a provisional, priority-ordered buyer hint, peer to context.currency / language — rather than a permalink-owned field, so it propagates to checkout, cart, and catalog through their existing context reference and needs no permalink-specific handling.

Discovery

Businesses advertise dev.ucp.shopping.permalink with config.endpoint, an absolute HTTPS endpoint.

{
  "ucp": {
    "capabilities": {
      "dev.ucp.shopping.permalink": [
        { "version": "…", "spec": "…", "schema": "…", "config": { "endpoint": "https://merchant.example/buy" } }
      ]
    }
  }
}

URL shape

{endpoint}/{items}?{query}

• Compact item path: comma-separated item_id_token:quantity pairs. A raw token is used when the identifier matches [A-Za-z0-9._-]+; otherwise it is ~ plus base64url-without-padding of the UTF-8 identifier, which avoids fragile percent-encoded path separators such as %2F.
• Query: UCP field paths, the continue_to control, and non-UCP parameters (preserved on the redirect by default when safe).

Playground & examples: https://ucp-permalink.vercel.app

---

Checklist

• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• I have followed the Contributing Guide
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.

[jamesandersen]

Thanks for the note on universal links