> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  This is the entry point into the API reference. For product concepts and the **Loyalty hub**, see [Loyalty program overview](/build/loyalty-overview). For an integration-oriented map of the member journey, see [Loyalty v2 developer overview](/guides/loyalty-v2-overview).
</Info>

Legacy `/v1/loyalties` remains in maintenance mode. For new integrations, use Loyalty v2. See [Legacy loyalty API](/api-reference/loyalties/introduction-to-legacy-loyalty).

## 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

<CardGroup cols={2}>
  <Card title="Programs" icon="layer-group" href="/api-reference/loyalty-v2-programs-overview">
    Create and manage programs, and assign wallets, earning rules, tiers, and rewards.
  </Card>

  <Card title="Members" icon="user" href="/api-reference/loyalty-v2-members-overview">
    Enroll members, read memberships, adjust points, list transactions, pay with points, and purchase rewards.
  </Card>

  <Card title="Examine" icon="magnifying-glass" href="/api-reference/loyalty-v2-examine-overview">
    Dry-run earning and reward evaluation for member portals and checkout previews.
  </Card>

  <Card title="Card definitions" icon="wallet" href="/api-reference/loyalty-v2-card-definitions-overview">
    Configure point wallets: pending points, expiration, limits, and pay-with-points exchange.
  </Card>

  <Card title="Earning rules" icon="bolt" href="/api-reference/loyalty-v2-earning-rules-overview">
    Define triggers and earnings for orders, custom events, and segment entry.
  </Card>

  <Card title="Rewards" icon="gift" href="/api-reference/loyalty-v2-rewards-overview">
    Build the reward catalog members can purchase with points.
  </Card>

  <Card title="Benefits" icon="box-open" href="/api-reference/loyalty-v2-benefits-overview">
    Define automatic material or digital grants from earning rules.
  </Card>

  <Card title="Tier structures" icon="ranking-star" href="/api-reference/loyalty-v2-tier-structures-overview">
    Configure tier levels and read tier progress on memberships.
  </Card>

  <Card title="Reports" icon="chart-line" href="/api-reference/loyalty-v2-reports-overview">
    Read aggregated spending, earnings, tier movements, and earning-rule statistics.
  </Card>
</CardGroup>

## 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         |

<Warning>
  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](/guides/loyalty-v2-take-to-production#troubleshooting).
</Warning>

## Shared platform APIs

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

* [Authentication](/guides/authentication) and regional base URLs from [API overview](/guides/api-overview#choose-the-right-api-endpoint)
* [Customers](/api-reference/customers/create-customer) before membership
* [Orders](/api-reference/orders/create-order) with `status: PAID` for order-paid earning rules and pay with points
* [Custom events](/api-reference/events/track-custom-event) for event-based earning rules
* Discount or gift [campaigns](/build/campaign-overview) when rewards or benefits issue vouchers or credits
* [Async actions](/api-reference/async-actions/get-async-action) for background enrollment

## Related resources

* [Loyalty v2 developer overview](/guides/loyalty-v2-overview) for the member journey, constraints, and documentation map.
* [Integrate loyalty v2](/guides/loyalty-v2-integrate) for step-by-step API flows with example payloads.
* [Take loyalty v2 to production](/guides/loyalty-v2-take-to-production) for go-live and troubleshooting.
* [Loyalty program overview](/build/loyalty-overview) for the product model and rollout context.
* [Loyalty key concepts](/build/loyalty-key-concepts) for point wallets, earning rules, rewards, tiers, and benefits.
* [Legacy loyalty API](/api-reference/loyalties/introduction-to-legacy-loyalty) for the maintenance-mode `/v1/loyalties` endpoints.