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.
- Author
- OrcaQubits ↗
- Repository
- agentic-commerce-skills-plugins ↗
- Licence
- MIT
- Last repository change
- 14.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.
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
- Before writing code
- Conceptual Architecture
- Use cases
- Implementation Guidance
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\",…