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

> Understand the new loyalty program model and how its components work together.

The new loyalty program model defines how members earn, keep, and spend points through modular components. This new model introduces also the completely new `v2/loyalties` API. In the dashboard, you manage the loyalty model in a new section called **Loyalty hub**.

<Info>
  For definitions of the individual components — point wallets, earning rules, tier structures, benefits, and rewards — see [Loyalty key concepts](/build/loyalty-key-concepts).
</Info>

## New loyalty: Roadmap

The new loyalty program model – loyalty v2 – is rolled out over several phases.

<Steps>
  <Step title="Initial phase">
    <Badge color="blue">You're here!</Badge>

    Loyalty v2 is enabled for everyone. New organizations and the existing organizations which don't use the legacy loyalty can use only the new loyalty solution.

    The Loyalty v2 API is available for production integrations during the initial phase. Voucherify avoids breaking changes to published contracts whenever possible. Some endpoint pages may still be marked as "work in progress documentation". Voucherify may still improve the API and the **Loyalty hub** UI. Follow the [release notes](/changelog/changelog) and contact your Technical Account Manager for change notifications that affect your integration.

    If you use or used the legacy loyalty, you can still continue to do so. However, Voucherify team will contact you with the details regarding future migration to the new solution.

    <Info>
      <Badge color="gray">Legacy loyalty maintenance</Badge>

      The legacy loyalty will be eventually sunset. As a result, it's not going to be further developed. Only critical issues will be fixed.
    </Info>
  </Step>

  <Step title="Expansion">
    We continue to add new features and API endpoints to the new loyalty solution. Also, the developers improve the overall loyalty v2 and fix the issues found.

    Planned features:

    * Additional customization for each tier level and guardrails.
    * Partial refund handling.
    * Support for household cards.
    * Advanced analytics.

    The roadmap is not final and is subject to change.
  </Step>

  <Step title="Legacy loyalty migration">
    If you use the legacy loyalty, you'll have to prepare for the migration to the new loyalty solution. You'll need to recreate your integration of the loyalty system to use the new API.

    <Warning>
      Migration from existing loyalty campaigns is not currently automated.

      Members, points, rewards, and campaign configuration from existing loyalty campaigns cannot currently be moved automatically to new loyalty programs. Voucherify is investigating migration support, but organizations should expect integration changes.
    </Warning>
  </Step>

  <Step title="Final sunset of legacy loyalty">
    Once everyone migrates to the new loyalty solution, the legacy loyalty is turned off.

    The new loyalty solution becomes the only loyalty system in Voucherify.
  </Step>
</Steps>

<Tip>
  Visit [Voucherify roadmap](https://voucherify.atlassian.net/jira/discovery/share/views/4fe91d57-02f9-4cbf-a10d-baa28417ee9c "Voucherify roadmap") to see the latest updates and planned features for the new loyalty solution.
</Tip>

## What changes in loyalty

The greatest change in the new loyalty program model is structural. It separates program setup into reusable components, headed by the support of multiple point wallets.

In existing loyalty campaigns, most settings belong to one campaign. This makes each campaign more isolated. If you need a similar setup in another campaign, you often need to configure it again. Also, the members can earn points only on one card that's governed by the campaign settings.

In the new model, you connect components inside a loyalty program. This helps you reuse configuration, manage more complex setups, and create programs with many point wallets. Your loyalty program members can earn points on different loyalty cards whose behavior is defined by separate point wallets.

## How components work together

A loyalty program connects all components — point wallets, earning rules, rewards, tier structures, and benefits — into one customer experience. For definitions of each component, see [Loyalty key concepts](/build/loyalty-key-concepts).

A simplified structure looks like this:

* The loyalty program contains the full setup.
* Point wallets store and manage points the members earn on their loyalty cards.
* Earning rules decide when members earn points or benefits.
* Rewards define what members can redeem.
* Tier structures group members into levels.
* Benefits grant points, material objects, or digital incentives automatically.

This structure makes loyalty programs more flexible. Instead of building every rule directly inside one campaign, you create components and connect them where they are needed.

For example, one program can use multiple point wallets. One reward can have different prices in different wallets. One tier can change earning limits or reward prices for members who qualify for it.

For the simplified end-to-end flow of how points move through a program, see [How it works](/build/loyalty-key-concepts#how-it-works) in Loyalty key concepts.

## Differences from existing loyalty campaigns

The new loyalty program model expands what marketers can build compared with existing loyalty campaigns.

Existing loyalty campaigns are more isolated. They use one point balance and keep most configuration inside one campaign. New loyalty programs use reusable components, multiple point wallets, wallet-specific reward prices, and more advanced tier behavior.

Additionally, the new loyalty program model improves security and fraud prevention. For example, it offers guardrails like point spending and earning limits, earning rule trigger limits, reward purchase limits, and more.

| Area                 | Existing loyalty campaigns                                     | New loyalty programs                                                                                       |
| -------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Program structure    | Most configuration belongs to one campaign                     | Configuration is separated into reusable components                                                        |
| Point wallets        | One point balance per campaign                                 | Multiple point wallets in one program                                                                      |
| Earning logic        | Multiple earning rules but each with one earning configuration | Multiple earning rules with multiple earning configurations, with the first matching configuration applied |
| Rewards              | One reward price                                               | One reward can be connected to multiple point wallets with different prices                                |
| Tiers                | One tier structure in one campaign                             | One tier structure in one program for one point wallet, with tier mappings for selected rules              |
| Households and teams | Not supported                                                  | Household and team wallets are planned to support shared earning models                                    |

Detailed configuration options are covered in the dedicated feature articles.

## Program limits

Program limits define how large one loyalty program can be.

Current limits:

* Up to 10 point wallets in one loyalty program
* Up to 100 rewards in one loyalty program
* Up to 100 earning rules in one loyalty program
* One tier structure in one loyalty program
* Up to 10 tier levels in one tier structure
* Up to 100,000 members in one loyalty program

These limits help you decide when to keep configuration in one program and when a separate program may be needed.

## Why use the new loyalty program model

The new model is useful when a program needs more flexibility than one point balance and one isolated campaign setup:

* Reusable configuration: Create components once and connect them where they are needed.
* Multiple point wallets: Manage different point balances or point currencies in one program.
* More control over points: Configure pending periods, expiration, earning limits, spending limits, refunds, and pay with points.
* Tier-specific behavior: Use tier mappings to adjust selected rules for different member levels.
* Larger program structures: Build complex loyalty setups without creating separate isolated campaigns for every variation.
* Improved experience: The new loyalty program model will be developed, while the legacy loyalty will be eventually sunset and only critical issues will be fixed.

## Support and feedback

We are continuously developing the new loyalty solution.

If you need additional support, you miss a feature, or you want to share your feedback, please reach out! Contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support form") or your Technical Account Manager.