Tier structures: Overview

Understand how tier structures define the tiering model that determines how Loyalty v2 members qualify for and move between tiers

A tier structure defines the tiering model for a loyalty program: the levels members can reach, and the rule that decides which level a member currently qualifies for. Tier structures are optional. A program can run entirely on points and rewards without any tiers.

Tier structure types

A tier structure qualifies members based on exactly one of two measures, set through its type:

• POINT_BALANCE: The member’s current point balance on the associated card.
• POINT_EARNED: The total points the member has earned over a given period, regardless of how many have since been spent or expired.

Only the configuration object matching the chosen type (point_balance or point_earned) can be set; the other must be left empty. If not specified, a tier structure defaults to no tier expiration (NO_RETENTION) and no automatic downgrade (NO_DOWNGRADE).

Tiers

Each tier structure contains its own nested tiers (like Bronze, Silver, and Gold) managed through dedicated create, list, update, and delete endpoints scoped to the parent structure. A tier structure can hold at most 10 tiers. Each tier can define its own downgrade behavior, or inherit the parent structure’s setting, which is the default when not specified. It can also set tier point expiration which will govern how points are retained when the member is in the tier.

Lifecycle

A tier structure is created in DRAFT status by default, and moves between DRAFT, ACTIVE, and INACTIVE through the activate, deactivate, and move tier structure back to draft endpoints – the same three-state pattern used by earning rules and rewards. Once a tier structure (or one of its tiers) leaves DRAFT, only name and metadata can still be updated. The qualification logic itself stays fixed to protect members already progressing through the tiers.

Assigning a tier structure to a program

A program can have at most one tier structure assigned at a time, connected through the program batch assignment endpoint. Unassigning a tier structure is only allowed while the program is in DRAFT status. Once the program is active, you can’t unassign a tier structure. This prevents members from losing their tier context on a live program.

Related resources

• Loyalty v2 API: Overview for the full Loyalty v2 API map.
• Programs overview for assigning a tier structure to a program.
• Members overview to see a member’s tier progress.
• Reports overview for program-level tier movement statistics.
• Create tier structures for the dashboard perspective on configuring tiers.
• Loyalty key concepts for the underlying tier concepts.