Use this guide to handle loyalty programs, memberships, benefits, and rewards within the Universal Commerce Protocol (UCP) checkout flow.
Overview
Use loyalty to build high-fidelity loyalty experiences within UCP flows. It ensures existing loyalty members can access their benefits during checkout sessions. By displaying a user's tier, eligible rewards, and immediately applicable benefits before they finalize a purchase, you can provide a seamless experience and reduce friction in the checkout funnel.
Google's loyalty experience builds directly on the standard UCP loyalty data models. See the UCP Loyalty Key Concepts guide for detailed explanations of core entities, relationships, and lifecycle states.
Benefits of loyalty
Loyalty supports the following core use cases for known program members:
- Price-impacting benefits: apply real-time member-only discounts and free shipping offers, and clearly attribute the source of the savings.
- Non-price benefits: transparently display the rewards earned from the current transaction or the rewards applicable to future purchases.
- Status recognition: verify and display the user's specific loyalty tier and status achievements within your program.
Additionally, for merchants, loyalty improves user retention and conversion rates by surfacing personalized loyalty benefits and reassuring users that their member status is recognized on Google's agentic surfaces.
Prerequisites
To use loyalty, ensure your integration meets the following requirements:
- You must implement identity linking. Google experiences only support verified loyalty tiers and benefits. Provisional loyalty claims are not supported.
- Publish your UCP profile at
/.well-known/ucpand include thedev.ucp.common.loyaltycapability extending the applicable core shopping capabilities. Google only supports loyalty on checkout. - Enable discounts. While loyalty handles membership state and reward earning forecasts, discounts are required to specify the monetary effect of any applicable price-impacting loyalty benefits (such as member-only pricing or free shipping).
Error handling and user feedback
Loyalty benefits apply only when a user has an eligible membership. To represent these memberships in your integration, use reverse-domain identifiers as map keys.
You must handle loyalty using identity linking:
- Identity linking: once a user is authenticated through identity
linking, securely determine
their membership from their identity and populate the
loyaltydata. Use the reverse-domain identifier that corresponds to their membership.
For a complete list of standard error codes and instructions on returning recoverable messages, see Error codes.
Next steps
View the API payloads and technical implementation details for your UCP version: