Mapping a Shopify points program onto the v2026-08-25 loyalty extension: fixtures and five questions

[yangw831]

We run a loyalty app for Shopify merchants. We ran our production program logic against a synthetic merchant (so the fixtures carry no customer data) and mapped the output onto the loyalty extension merged in PR #340 and released in v2026-08-25, to see what fits and what does not. Everything is published as versioned fixtures that validate against schemas/common/loyalty.json at v2026-08-25:

https://www.stabilerewards.com/ucp-loyalty-reference/brief/

ucp-walkthrough-scene2-clip-v2.mp4

What maps cleanly

• Program name, reverse-domain key (example.harborpine.rewards), and provisional.
• Earn rules as membership_tier_benefit descriptions under a single "Member" tier (single-status program, as the tiers description allows).
• Cart earning as rewards[].earning_forecast, integer points with a breakdown whose benefit_ids resolve to those benefits. A $72 cart earns 360 base + 150 first-order bonus = 510; a $28 cart under the $35 minimum earns 0 with a membership_benefit_ineligible warning.
• A verified member with provisional: false and a masked display_id.

What we kept out, on purpose

Available balance, reward codes, point holds, and settlement. The spec defers redeemable value to a payment instrument or future redemption capability, so we publish our Shopify lifecycle (issue → idempotent retry → settle on order creation → release on expiry) as a separate, explicitly non-UCP fixture in case it is useful input.

What Shopify stores publish today

Following up on the storefront probe in discussion #856: Shopify already serves a platform-hosted profile at /.well-known/ucp for each store. On 2026-09-24 we fetched it from four Shopify stores (our own test store plus three large public ones). All four were identical: 2026-08-25, nine capabilities (catalog search and lookup, cart, checkout, discount, fulfillment, order, identity linking, plus dev.shopify.catalog), an MCP service, and no dev.ucp.common.loyalty. Because Shopify hosts the profile, a merchant's loyalty app has no way to add the extension or populate the loyalty map itself.

Questions we could not answer from the spec

1. How does a loyalty provider reach a platform-hosted profile? When the platform hosts the business profile (as Shopify does for every store), what is the intended path for a third-party loyalty program's data to appear in its cart and checkout responses: a platform-level extension point, the Provider participant type proposed in issue #384, or something else?
2. Earning forecast for a non-member. The loyalty map is keyed by an accepted claim or by membership resolved from an authenticated identity. The most common discovery question, "what would this cart earn if I join?", has neither. Is the intended pattern a platform-sent program claim answered with provisional: true, or is this out of scope for the extension? (This seems adjacent to the offer-discovery half of issue #384.)
3. id when nothing is verified. loyalty_membership.id is required, and the guidelines forbid raw stable member identifiers. For a provisional or prospective response we return a constant ("unverified"). Is a non-identifying placeholder the expected approach, or should id be optional while provisional is true?
4. Redemption thresholds are not tiers. Many Shopify programs call "500 points → $5 off" a tier. We described those as benefit text only, since membership_tier is status. Is that the reading the authors intended?
5. Earn minimums. We reused membership_benefit_ineligible for "cart is under the earning minimum". The code is defined for monetary benefits. Is that an acceptable reuse, or should earn-side conditions be expressed differently?

Happy to adjust the fixtures to whatever the maintainers consider correct, and to share the redemption lifecycle in more detail if it helps the future redemption work.

— Yang, StabileRewards