UCP Loyalty Extension
Before writing code
Fetch live spec: Web-search site:ucp.dev specification common extensions loyalty and fetch the page for the exact eligibility claim shape, membership/tier schema, and current error codes.
Conceptual Architecture
Three use cases
Loyalty exists to serve three distinct things, and conflating them causes most design mistakes:
- Price-impacting benefits — member discounts, member shipping. These flow through the discount extension, not through loyalty fields directly.
- Non-price benefits — rewards tracking, dedicated support. Value that is real but does not move the total.
- Status recognition — tier verification for display.
The model
- Memberships — independent enrollment pathways within a brand, modeled as separate sibling entries. A "Rewards Club" and a "Co-branded Credit Card" are two memberships, not one membership with two facets.
- Tiers — achievement ranks within a membership. Members typically hold one active tier per membership, though parallel status dimensions allow multiple concurrent tiers.
- Benefits — perks tied to tier/membership status. Immediate-value (5% off) and delayed-value (priority support).
- Rewards — quantifiable value earned from a transaction. Distinct from redeemable balances, which are payment instruments, not loyalty fields.
That last distinction matters: points you earn are rewards; points you spend are a payment instrument and belong in the payment flow (see ucp-split-payments).
Namespacing
Programs use reverse-domain naming — com.example.loyalty, com.example.rewards.card — to prevent collisions and establish provenance. The same reverse-domain key the platform submits is the key the business returns as the membership identifier.
Claims and verification
The platform submits buyer claims via context.eligibility in requests. The business either verifies the claim or determines membership from authenticated identity.
Three outcomes:
| Outcome |
Response |
| Verified |
provisional: false, active tiers included, masked display_id set, price-impacting benefits applied via the discount extension |
| Unverified |
provisional: true, no display_id |
| Invalid |
error message with code eligibility_invalid |
All accepted claims must be resolved at checkout completion. A provisional membership cannot survive into a completed order — either it verifies or its benefits come off.
Where it surfaces
Loyalty spans catalog, cart, and checkout. Monetary benefits appear in totals or line_items with loyalty attribution; reward forecasts include earning breakdowns linked to specific tier benefits.
Implementation Guidance
- Never render a
display_id for a provisional membership — that is exactly the field the spec withholds until verification, and showing an unverified one implies a status the buyer may not have.
- Apply price-impacting benefits through the discount extension so they reconcile with every other discount rather than becoming a parallel pricing path.
- Model each enrollment as its own membership entry, even when they share a brand.
- Treat
provisional: true at completion time as a hard error path, not a warning.
- Reference implementation: https://github.com/Universal-Commerce-Protocol/samples
1---2name: ucp-loyalty3description: Implement the UCP Loyalty extension — memberships, tiers, benefits, and rewards surfaced across catalog, cart, and checkout, with reverse-DNS program namespaces, `context.eligibility` claims, and provisional vs verified membership. Use when adding member pricing, tier recognition, or rewards forecasting to a UCP flow.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/ucp-loyalty7---89# UCP Loyalty Extension1011## Before writing code1213**Fetch live spec**: Web-search `site:ucp.dev specification common extensions loyalty` and fetch the page for the exact eligibility claim shape, membership/tier schema, and current error codes.1415## Conceptual Architecture1617### Three use cases1819Loyalty exists to serve three distinct things, and conflating them causes most design mistakes:20211. **Price-impacting benefits** — member discounts, member shipping. These flow through the **discount extension**, not through loyalty fields directly.222. **Non-price benefits** — rewards tracking, dedicated support. Value that is real but does not move the total.233. **Status recognition** — tier verification for display.2425### The model2627- **Memberships** — independent enrollment pathways within a brand, modeled as **separate sibling entries**. A "Rewards Club" and a "Co-branded Credit Card" are two memberships, not one membership with two facets.28- **Tiers** — achievement ranks within a membership. Members typically hold **one active tier per membership**, though parallel status dimensions allow multiple concurrent tiers.29- **Benefits** — perks tied to tier/membership status. Immediate-value (5% off) and delayed-value (priority support).30- **Rewards** — quantifiable value *earned* from a transaction. Distinct from redeemable balances, which are **payment instruments**, not loyalty fields.3132That last distinction matters: points you *earn* are rewards; points you *spend* are a payment instrument and belong in the payment flow (see `ucp-split-payments`).3334### Namespacing3536Programs use **reverse-domain naming** — `com.example.loyalty`, `com.example.rewards.card` — to prevent collisions and establish provenance. The same reverse-domain key the platform submits is the key the business returns as the membership identifier.3738### Claims and verification3940The platform submits buyer claims via **`context.eligibility`** in requests. The business either verifies the claim or determines membership from authenticated identity.4142Three outcomes:4344| Outcome | Response |45|---------|----------|46| **Verified** | `provisional: false`, active `tiers` included, masked `display_id` set, price-impacting benefits applied via the discount extension |47| **Unverified** | `provisional: true`, **no** `display_id` |48| **Invalid** | error message with code `eligibility_invalid` |4950**All accepted claims must be resolved at checkout completion.** A provisional membership cannot survive into a completed order — either it verifies or its benefits come off.5152### Where it surfaces5354Loyalty spans catalog, cart, and checkout. Monetary benefits appear in `totals` or `line_items` with loyalty attribution; reward forecasts include earning breakdowns linked to specific tier benefits.5556## Implementation Guidance5758- Never render a `display_id` for a provisional membership — that is exactly the field the spec withholds until verification, and showing an unverified one implies a status the buyer may not have.59- Apply price-impacting benefits through the discount extension so they reconcile with every other discount rather than becoming a parallel pricing path.60- Model each enrollment as its own membership entry, even when they share a brand.61- Treat `provisional: true` at completion time as a hard error path, not a warning.62- Reference implementation: https://github.com/Universal-Commerce-Protocol/samples