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

# Create tier structures

> Set up rules that group customers based on their loyalty activity

Tier structures control how you assign customers to tiers and how their tier status changes over time.

## Create a tier structure

Go to **Loyalty hub** > **Tier structures** and select **Create tier structure**.

The tier structure builder informs which steps require your action.

<Steps>
  <Step>
    ### General settings

    Set the basic behavior of the tier structure.

    **Name tier structure**: enter a name for the structure.

    <Tabs>
      <Tab title="Point balance">
        Uses the customer's current point balance on their loyalty card to determine tier assignment.
      </Tab>

      <Tab title="Points earned">
        Uses the total points earned over a tracking period to determine tier assignment.

        When to apply tier change:

        * **Immediately**: Updates when the threshold is reached.
        * **Next tracking period**: Updates at the start of the next cycle.

        **Tracking period value**: Length of the tracking period.

        **Period unit**: Day(s), Week(s), Month(s), Year(s). The units are defined by the Project settings (time zone and locale).
      </Tab>
    </Tabs>

    **Point wallet**: Select the point wallet used to calculate tiers.

    <Warning>
      Tying a tier structure to a point wallet that is already active makes the tier structure take effect immediately.

      A loyalty program can only have one tier structure assigned to it.
    </Warning>

    Complete all required fields. If something is missing or invalid, you will see **Action required**.
  </Step>

  <Step>
    ### Tier levels point-base

    Configure tier levels based on the point balance.

    This tier level path is optional. Set it up only if you want tiers based purely on point balance. At least one tier must exist across the two tier-level paths (point-based or segment-based) before you can proceed. Any path you configure must cover points 0 to ∞ without gaps or overlaps.

    Tier levels are shared with the segment-based path. Both count toward the same 10-tier limit. Each tier you create only appears in the path it was created under. A tier added here won't appear in **Tier levels segment-base**, and vice versa.

    <Warning>
      If tier ranges leave any points uncovered or overlap, you'll see an **Action required** message. For example, if a middle tier is left with no maximum: "A middle tier has no maximum — only the highest tier can be unlimited."
    </Warning>

    Use **+ Add tier levels** to add a tier.

    For each tier, define:

    * **Tier name**: Label of the tier (for example Bronze, Silver, Gold).
    * **Minimum value (points)**: Points required to reach this tier. When you add a new tier, this is automatically set to one point higher than the previous tier's **Maximum value (points)**. You can adjust it manually, though.
    * **Maximum value (points)**: Upper limit of points for this tier. Leave this field empty to make the tier **Unlimited**. This is only allowed for the highest tier; leaving it empty on any other tier triggers the **Action required** mentioned above.
    * **Allow tier downgrade for this level**: Enabled by default. Uncheck to create a VIP tier where members keep their level forever.

    The tier's points range is calculated automatically from its Minimum and Maximum values and shown in the tier's header.

    Each tier also has its own **Metadata** section, where you can define custom key/type/value properties, either by adding an unknown property directly or by adding it to the schema.
  </Step>

  <Step>
    ### Tier levels segment-base

    Configure tier levels that also require a [customer segment](/prepare/customer-segments), a group of customers who share a selected attribute or behavior.

    This path is optional. Set it up only if you want segment-gated tiers. At least one tier must exist across the two tier-level paths (point-based or segment-based) before you can proceed. Any path you configure must cover points 0 to ∞ without gaps or overlaps.

    Tier levels are shared with the point-based path. Both count toward the same 10-tier limit, and each tier you create only appears in the path it was created under. A tier added here won't appear in **Tier levels point-base**, and vice versa.

    <Warning>
      If tier ranges leave any points uncovered or overlap, you'll see an **Action required** message. For example, if a middle tier is left with no maximum: "A middle tier has no maximum — only the highest tier can be unlimited."
    </Warning>

    Use **+ Add tier levels** to add a tier.

    For each tier, define:

    * **Tier name**: Label of the tier (for example Bronze, Silver, Gold)
    * **Minimum value (points)**: Points required to reach this tier. When you add a new tier, this is automatically set to one point higher than the previous tier's **Maximum value (points)**. You can adjust it manually, though.
    * **Maximum value (points)**: Upper limit of points for this tier. Leave this field empty to make the tier **Unlimited**. This is only allowed for the highest tier; leaving it empty on any other tier triggers the **Action required** mentioned above.
    * **Customer segment**: Required for every tier in this path. The customer must meet both the points range and belong to the selected segment (**AND** logic; there's no **OR** option here). You can select different segments for each tier.
    * **Allow tier downgrade for this level**: Enabled by default. Uncheck to create a VIP tier where members keep their level forever.

    The tier's points range is calculated automatically from its Minimum and Maximum values and shown in the tier's header.

    Each tier also has its own **Metadata** section, where you can define custom key/type/value properties, either by adding an unknown property directly or by adding it to the schema.
  </Step>

  <Step>
    ### Tier expiration

    Choose how a tier expires.

    <Tabs>
      <Tab title="Immediate expiration">
        Tier ends instantly when member criteria changes.
      </Tab>

      <Tab title="Fixed duration">
        Tier is valid for a set number of days from entry:

        * **Duration**: Number of periods the tier stays valid.
        * **Period unit**: Day(s), Month(s), Year(s).

        <Accordion title="Fixed duration: Example">
          The **Fixed duration** is set to 30 days in a **Point balance**-based tier structure. A member earns 150 points and reaches the Silver tier on 20 July. On 25 July, the member then spends their points and falls to the Bronze tier. Then, the **Fixed duration** setting starts counting 30 days from 20 July (the day when the member reached the Silver tier) and the tier will expire on right on midnight 00:00 of the 20 August.
        </Accordion>
      </Tab>

      <Tab title="Calendar Expiry">
        Tier expires on a set date each year:

        * **Expiry date (MM-DD)**: Pick a day and month from the calendar. This field is required. You can pick up to 20 expiry dates.
      </Tab>

      <Tab title="Sliding Expiry">
        <Info>
          Currently unsupported.

          Follow [Voucherify release notes](/changelog/changelog) for latest updates.
        </Info>

        Expires the tier if no qualifying action occurs within a set number of days.
      </Tab>
    </Tabs>

    ### Tier downgrade configuration

    Choose how tier levels are reassessed when a member no longer qualifies.

    <Tabs>
      <Tab title="No downgrade">
        Members keep their current tier when expiration triggers or they no longer qualify for the current tier. This means that members never move to a lower tier.
      </Tab>

      <Tab title="Multi-level downgrade (full reassessment)">
        Customer is moved to the highest eligible tier based on their current performance.

        When you select **Multi-level downgrade**, you can enable **Grace period before downgrade**, a waiting period after disqualification before the downgrade is enforced. When enabled, set:

        * **Grace period**: Length of the delay.
        * **Unit**: Day(s), Month(s), Year(s).
        * **Round up grace period**: Rounds the delay to the end of the selected unit (unchecked by default).

        <Accordion title="Multi-level downgrade: Example">
          The **Multi-level downgrade** is set in a **Point balance**-based tier structure. A member earns 250 points and reaches the Gold tier on 20 July. On 25 July, the member spends 200 points, so their balance is 50 points, which is in the range of the Bronze tier. The member will be downgraded to the Bronze tier immediately.

          However, if there's a grace period of one month, the member will not be downgraded to the Bronze tier until for one month after the expiration date (19 August, 23:59:59). If the grace period is rounded up to the end of the month, the member will not be downgraded to the Bronze tier until 31 August, 23:59:59.
        </Accordion>
      </Tab>

      <Tab title="Single-level downgrade (step-by-step drop)">
        A customer can only be downgraded one tier at a time during each evaluation.

        When you select **Single-level downgrade**, you can enable **Grace period before downgrade**, a waiting period after disqualification before the downgrade is enforced. When enabled, set:

        * **Grace period**: Length of the delay.
        * **Unit**: Day(s), Month(s), Year(s).
        * **Round up grace period**: Rounds the delay to the end of the selected unit (unchecked by default).
      </Tab>
    </Tabs>

    <Note>
      Expiration and downgrade are configured independently. Expiration controls when tier levels are re-evaluated. Downgrade controls how members move to a lower tier after expiration.
    </Note>
  </Step>

  <Step>
    ### Metadata

    Add custom attributes for tracking, optimizing, or experimenting.

    You can either:

    * **Use an existing metadata schema**.
    * **Add unknown property**: Metadata that isn't defined and won't be added to the schema.
    * **Add to schema**: Define new metadata schema. Once saved, reload the schema to use the new metadata.

    <Note>
      Read [Metadata](/prepare/metadata) to learn more about custom attributes.
    </Note>
  </Step>

  <Step>
    ### Summary

    Review your configuration before saving.

    The summary lists a card for each step, showing condensed details of your configuration. Use **Go to step** on any card to return to that section and make changes.

    **Save draft** and **Save and activate** both become available only once there's no outstanding **Action required** anywhere in the configuration. **Save draft** saves the structure without activating it. **Save and activate** saves it and activates it immediately. Once activated, you can't edit the tier structure and its tiers with the exception of name and metadata.
  </Step>
</Steps>

The tier structure is now created and can be used in a loyalty program.

## Tier structures view

The **Tier structures** view lists all configurations created in your project.

Each structure appears with its status and key settings.

### Overview

This list shows key details of each tier structure.

* **Status**: **Draft** (not yet activated) or **Active**.
* **Name**: Name of the tier structure.
* **Type**: The tier type configured in **General settings**.
* **Point wallet**: The wallet the structure is linked to.
* **Expiration**: The expiration model configured in **Tier expiration**, shown as a short label (for example **Calendar** for Calendar Expiry), or a dash if none is set.
* **Downgrade**: The downgrade behavior configured in **Tier downgrade configuration**, or a dash if none is set.
* **Tier levels**: Number of defined tiers, or a dash if none are configured.
* **Loyalty programs**: Programs where the structure is assigned, or a dash if none.

Use **Edit** or **Delete** from the ⋮ menu on any row to manage a structure.

### Structure details

Select a structure name to open its details panel.

The panel header shows the structure's ID, creation date, and status, along with **Edit** and close controls. If the structure is in **Draft** status, an **Activate** button also appears; activating it makes it available to be assigned to a point wallet, and if that point wallet is already active, tier assignments can start applying immediately.

<Warning>
  Once a structure is **Active**, it cannot be deactivated in the UI or through the API.
</Warning>

The panel has three tabs:

* **Dashboard**: Summary cards for **General settings**, **Tier levels**, and **Tier expiration** (which also includes the downgrade configuration).
* **Activity**: A log of events for the structure, such as its creation and tier creation events.
* **Metadata**: The structure's metadata, shown as raw JSON.

Dashboard cards shown: General settings, Tier levels, Tier expiration (includes downgrade).

## Using tier structures in programs

Assign a tier structure to a point wallet from within the program Designer.

### Adding a tier structure

Each point wallet card shows a **No tier structure assigned** placeholder if none is set. Selecting it opens a search field where you can pick an existing tier structure or select **+ Create new** to create one on the spot.

You can assign only one tier structure per program. If another point wallet in the same program already has one assigned, you'll see a message telling you to unassign it there first.

### How it appears in the program

Once assigned, the point wallet card shows the structure's name, status, a condensed summary (type, expiration, downgrade, and tier level count), and its configured tiers.

### Removing a tier structure

Select **Unassign from program** next to the assigned structure on the wallet card. This only removes the assignment; to delete the tier structure itself, go to the **Tier structures** overview list.

<Warning>
  Once a tier structure is assigned to an active point wallet in an active loyalty program, it cannot be unassigned.
</Warning>