Skip to content
Skills Library
Programming · Building & coding

ucp-permalink

/ucp-permalink

Implement the UCP Permalink capability — browser-addressable shopping intent URLs that initialize cart/checkout state via a compact item path and UCP field-path query parameters, then redirect the buyer. Use when building campaign links, QR/social buy links, buyer prefill, or store-pickup deep links.

Licence
MIT
Last repository change
14.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Implement the UCP Permalink capability — browser-addressable shopping intent URLs that initialize cart/checkout state via a compact item path and UCP field-path query parameters, then redirect the buyer. Use when building campaign links, QR/social buy links, buyer prefill, or store-pickup deep links.

Original author description

Implement the UCP Permalink capability — browser-addressable shopping intent URLs that initialize cart/checkout state via a compact item path and UCP field-path query parameters, then redirect the buyer. Use when building campaign links, QR/social buy links, buyer prefill, or store-pickup deep links.

How it works

  1. Before writing code
  2. Conceptual Architecture
  3. Use cases
  4. Implementation Guidance
Original SKILL.md headings · 69 lines, 465 words
SKILL.md preview
---
name: ucp-permalink
description: Implement the UCP Permalink capability — browser-addressable shopping intent URLs that initialize cart/checkout state via a compact item path and UCP field-path query parameters, then redirect the buyer. Use when building campaign links, QR/social buy links, buyer prefill, or store-pickup deep links.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# UCP Permalink Capability

## Before writing code

**Fetch live spec**: Web-search `site:ucp.dev specification permalink` and fetch the page for the exact path grammar, encoding rules, and the current list of addressable field-paths. The encoding rules in particular are easy to get subtly wrong — read them live.

## Conceptual Architecture

### Permalink is not an API

The defining property: **a permalink is a GET browser navigation, not a REST operation.** It has no request body, no auth header, and no JSON response. It is a URL a human can click from an email, a QR code, or a social post, which lands them in a shopping session with state already applied.

### Structure

A permalink is appended to an endpoint discovered from the business's UCP profile (e.g. `https://merchant.example/buy`):

```
/{items}?{query}
```

**Item path** — comma-separated `id:quantity` pairs:

```
/sku_123:2,sku_456:1
```

**Item encoding** — this is the part implementations get wrong. Simple identifiers matching `[A-Za-z0-9._-]+` are used directly. Anything else — notably opaque platform IDs like `gid://shopify/ProductVariant/70881412` — must be **base64url-encoded with a `~` prefix**, because raw slashes and colons break HTTP routing.

**Query parameters** — UCP **field-paths** mapped to values:

```
?buyer/email=alice@example.com&discounts/codes/0=SAVE10
```

The field-path addresses the cart/checkout schema directly, including extension fields. Array positions are numeric segments.

### Resolution

The business responds **`303 See Other`**, applying safe inputs to server-side state and redirecting to a buyer-facing destination.

Two rules constrain what a permalink may do:

1. **Query parameters cannot override line items.** The item path is authoritative.
2. **A business MUST NOT treat loading a permalink as authorization to place an order.** A permalink initializes state; it never commits a purchase. Anyone can construct one.

### `continue_to`

Specifies where the buyer navigates after processing. It **must be validated as same-origin** — an unvalidated `continue_to` is an open-redirect vulnerability, and it is the most likely security defect in a permalink implementation.

### Pass-through parameters

Non-UCP parameters pass through unchanged for analytics and attribution, **unless sensitive**. Do not blindly forward everything — filter anything that could carry credentials or PII into a third-party analytics context.

## Use cases

- **Campaign links** — bundled items plus a discount code plus attribution
- **Buyer prefill** — email, location, preferred payment handler
- **Social and QR** — compact item path with a continuation link
- **Store pickup** — pre-selected fulfillment destination

## Implementation Guidance

- Validate and normalize every field-path before applying it; treat the query string as fully untrusted input.
- Reject or ignore field-paths that address fields the buyer should not control (payment instrument data, totals, order state).
- Keep permalinks short enough to survive QR encoding and SMS — that is the constraint the compact item syntax exists to satisfy.
- Return `303`, not `302` — the method-rewrite semantics matter here.
- Reference implementation: https://github.com/Universal-Commerce-Protocol/samples

Versions

The database has no other skills named ucp-permalink.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ddefaf6cff18 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ucp-cart
    Implement the UCP Cart capability (`dev.ucp.shopping.cart`) — a lightweight CRUD surface for collecting line items before purchase intent exists, and its conversion into a Checkout session. Use when building pre-checkout item collection, shareable carts, or cart-recovery flows…
  • 90ucp-fulfillment
    Implement the UCP Fulfillment extension — shipping and pickup methods, destinations, fulfillment groups, selectable options, and estimated delivery. Use when adding shipping/pickup logic to a UCP checkout.
  • 100ucp
    Use when the user wants to use the UCP CLI to find, compare, buy, or track products from online merchants, or to set up and troubleshoot the local UCP profile required for merchant-scoped operations. Covers global catalog search (\"find me X under $Y\"), named-merchant…
  • 100ucp-runtime-debugging
    Find out what the running Unity project is doing and why with `ucp logs`, `ucp run-tests`, `ucp exec`, `ucp profiler`, `ucp profile`, and `ucp frame capture`: read and follow console logs with filters, run edit-mode or play-mode tests by name pattern, execute registered editor…
  • 100ucp-assets
    Work with a Unity project's assets and files through the editor with `ucp asset`, `ucp files`, `ucp material`, `ucp references`, `ucp shader`, and `ucp script`: search and inspect assets, read and write ScriptableObject and material fields, move or rename assets without breaking…
  • 100ucp-agent-ready
    Publish or repair a Universal Commerce Protocol (UCP) profile so AI shopping agents can discover, read and transact with a store, verified against UCP Checker's independent validator. Use when asked to \"make this store agent-ready\", \"add UCP\", \"fix our /.well-known/ucp\",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.