Schema dev.uip.shopping.loyalty

UCP Loyalty Extension

Capability Name: dev.uip.shopping.loyalty
Version: 2026-01-23

Extends the Universal Commerce Protocol (UCP) Checkout schema to support complex profile or card-based loyalty scenarios. This specification details memberships, multi-wallet programs, tiers, and granular earning breakdowns.

JSON Schema ID

https://uip.dev/schemas/ucp/shopping/loyalty.json

Checkout

Entry Point

The entry point for the extension. It adds a loyalty object to the standard checkout response.

Property	Type	Description
loyalty	loyalty_object	Container for all loyalty-related data.

loyalty_object

Object

The main container holding identified memberships, program states, and transaction earnings.

Properties

Property	Type	Description
memberships	Array<Membership>	List of profiles or cards identified in the transaction.
programs	Array<Program>	Read Only State of loyalty programs and wallets.
earnings	Array<Earning>	Read Only List of specific earnings triggered by the transaction.

Program

A loyalty program associated with a specific membership.

Properties

id Required	string	Unique identifier for the program.
name Required	string	Human-readable name of the program.
membership Required	string	JSONPath reference to the membership (e.g., `$.loyalty.memberships[0]`).
wallets Required	Array<Wallet>	List of wallets attached to this program. Min items: 1.

Example

{
  "id": "f94c586c-af6f...",
  "name": "The Loyalty Club",
  "membership": "$.loyalty.memberships[0]",
  "wallets": [
    {
      "id": "main_wallet",
      "unit": "points",
      "balances": {
        "active": 1250,
        "pending": 500,
        "total": 1750
      }
    }
  ]
}

Membership

An identifier for the entity involved in the loyalty program (User or Card).

type Required	enum	The type of identifier. profile card
id Required	string	The unique identifier string.

Example

{
  "type": "profile",
  "id": "cd9105a3-078f-4c27-a6e1-6f26b51011ae"
}

Wallet

A specific container of value (points, cash, stamps) within a program. It tracks balances and tier progress.

id Required	string	Unique wallet identifier.
unit Required	string	Unit of measure (e.g., 'points', 'USD').
balances Required	Amount Breakdown	State of the wallet before this transaction.
earnings	Amount Breakdown	Impact of this transaction. Contains amounts expected to be earned.
tier	Tier Info	Current tier status.

Example

{
  "id": "main_wallet",
  "unit": "points",
  "balances": {
    "active": 1250,
    "pending": 500,
    "total": 1750
  },
  "earnings": {
    "active": 100,
    "pending": 0,
    "total": 100
  },
  "tier": {
    "current": {
      "id": "tier_silver",
      "name": "Silver"
    },
    "unitsToNext": 250
  }
}

Earning

Details of specific points or value expected to be earned in this session.

Property	Type	Description
title Required	string	Human-readable description.
target Required	enum	Scope of the earning. `session` `items` `bundle`
amount Required	integer	Total amount expected to be earned. ⚠ Represents minor units (1/100)
wallet Required	string	JSONPath reference to receiving wallet (e.g., `$.loyalty.programs[0].wallets[0]`).
activeFrom	date-time	RFC 3339 timestamp indicating when points become active.
allocations	Array<Allocation>	Detailed breakdown of where this earning was allocated (e.g., specific line items).

Example

{
  "title": "20 Points on the session",
  "target": "session",
  "amount": 200,
  "wallet": "$.loyalty.programs[0].wallets[0]"
}

Allocation

Breakdown of how the earning was allocated to a specific target.

path Required	string	JSONPath to the allocation target (e.g., `$.line_items[0]`).
amount Required	integer	Amount allocated in minor units.

Example

{
  "path": "$.line_items[0]",
  "amount": 200
}

Tier

Basic tier identification.

id Required	string	Internal ID of the tier.
name Required	string	Human-readable tier name.

Example

{
  "id": "tier_gold",
  "name": "Gold Tier"
}

Tier Info

Current tier status and progression.

current Required	Tier	Current tier.
next	Tier	Next tier to be achieved.
unitsToNext	integer	Points/Units required to reach the next tier in minor units.

Example

{
  "current": {
    "id": "tier_silver",
    "name": "Silver"
  },
  "next": {
    "id": "tier_gold",
    "name": "Gold"
  },
  "unitsToNext": 250
}

Amount Breakdown

Breakdown of points or value by status.

active Required	integer	Immediately available balance (minor units).
pending Required	integer	Balance awaiting confirmation or activation (minor units).
total Required	integer	Sum of active and pending balances (minor units).

Example

{
  "active": 1250,
  "pending": 500,
  "total": 1750
}