Loyalty v2 API: Overview

Map the Loyalty v2 API under /v2/loyalties: Programs, reusable components, members, examine, and reports

The Loyalty v2 API lives under /v2/loyalties. It manages modular loyalty programs: Reusable components (card definitions, earning rules, rewards, benefits, and tier structures), program assignments, members and their cards, dry-run examine calls, and aggregated reports.

This is the entry point into the API reference. For product concepts and the Loyalty hub, see Loyalty program overview. For an integration-oriented map of the member journey, see Loyalty v2 developer overview.

Legacy /v1/loyalties remains in maintenance mode. For new integrations, use Loyalty v2. See Legacy loyalty API.

How resources connect

Loyalty v2 separates configuration from runtime membership:

• Components are created independently under their own paths (/card-definitions, /earning-rules, /rewards, /benefits, /tier-structures).
• A program (/programs) is the container that assigns those components into one customer-facing setup. Activation requires at least one active card definition (point wallet in the dashboard) and one active earning rule.
• Members enroll under a program. Voucherify issues one loyalty card per active card definition assigned to that program.
• Examine endpoints estimate earnings and reward availability without writing balances.
• Reports return aggregated program and member statistics for dashboards and analytics.

Many integrations configure the program in the dashboard (Loyalty hub), then automate only the runtime member journey through the API.

API groups

Programs

Create and manage programs, and assign wallets, earning rules, tiers, and rewards.

Members

Enroll members, read memberships, adjust points, list transactions, pay with points, and purchase rewards.

Examine

Dry-run earning and reward evaluation for member portals and checkout previews.

Card definitions

Configure point wallets: pending points, expiration, limits, and pay-with-points exchange.

Earning rules

Define triggers and earnings for orders, custom events, and segment entry.

Rewards

Build the reward catalog members can purchase with points.

Benefits

Define automatic material or digital grants from earning rules.

Tier structures

Configure tier levels and read tier progress on memberships.

Reports

Read aggregated spending, earnings, tier movements, and earning-rule statistics.

Core objects and identifiers

Loyalty v2 uses program-scoped resources. Store these IDs in your system and pass the correct type on each call.

Object	ID prefix	Role in the integration
Program	lprg_	Parent container for wallets, rules, rewards, and members
Card definition (point wallet)	lcdef_	Defines how points behave on cards issued from that wallet
Member	lmbr_	Program-specific enrollment of a Voucherify customer
Loyalty card	lcrd_	Point balance for one wallet on one member
Earning rule	lern_	Trigger and effects that grant points or benefits
Reward	lrew_	Catalog item members can purchase with points
Benefit	lben_	Automatic grant (material or digital) from an earning rule
Tier structure / tier	lts_ / lt_	Levels and progress tied to a point wallet
Customer (shared)	cust_	Must exist before enrollment; not loyalty-specific

Do not interchange cust_… and lmbr_…. Member endpoints expect a member ID. Membership lookup can use a customer ID with the correct identification type. Mixing IDs is a common cause of 404 responses. See Take loyalty v2 to production.

Shared platform APIs

Loyalty v2 does not replace the rest of the Voucherify API. Runtime flows still use:

• Authentication and regional base URLs from API overview
• Customers before membership
• Orders with status: PAID for order-paid earning rules and pay with points
• Custom events for event-based earning rules
• Discount or gift campaigns when rewards or benefits issue vouchers or credits
• Async actions for background enrollment

Related resources

• Loyalty v2 developer overview for the member journey, constraints, and documentation map.
• Integrate loyalty v2 for step-by-step API flows with example payloads.
• Take loyalty v2 to production for go-live and troubleshooting.
• Loyalty program overview for the product model and rollout context.
• Loyalty key concepts for point wallets, earning rules, rewards, tiers, and benefits.
• Legacy loyalty API for the maintenance-mode /v1/loyalties endpoints.