The User Manual has moved! For the most up-to-date information, please visit our new site at docs.antavo.com.
We're committed to providing you with the best resources, and our new site offers an enhanced experience with the latest documentation. Thank you for your understanding and continued support.

Tiers are different levels of membership that offer increasing benefits to customers as they accumulate more points or spend more money with the brand. The higher the tier, the more rewards and exclusive benefits the customer receives.

In terms of tier upgrades and downgrades, Antavo uses both automatic and manual methods. Automatic upgrades and downgrades are action-driven, meaning that customers will be moved to a higher or lower tier based on their behavior or activity within the program. Manual upgrades and downgrades, on the other hand, are performed by Backoffice administrators, or they can also be workflow-mediated.

Antavo’s Tiers module allows you to configure several tier structures in the loyalty program, including invitation-only tiers and several built-in tier expiration options. The module was designed to extend the functionalities of the Levels module.

Find the configuration page of the Tiers module by clicking on the Modules icon in the sidebar and typing ‘Tiers’ into the search field. The list of tier structures that were already set up is presented with their names, their status (active/inactive) and the number of tiers included.

Setting up a new tier structure

  • Click ‘Create new structure’ in the sidebar on the left of the Tiers module

Basic settings

  • Define the unique ID – machine-readable ID of the tiers structure that can be used to refer to the tier structure in the Antavo APIs

  • Add the name of the tier structure – the human-readable name of the tier structure, that is the displayed name of the tier in the Antavo Backoffice and potentially to the customers on the membership site, and is accessible through the API as well

Tier structure type selection


Tier membership is calculated based on the number of points customers have accumulated (otherwise known as the score).
With the point-based type, it's possible to specify a list of actions (events) that should be considered when determining the tier status. Define the lists under the following fields:

  • Tier-up actions (required)
    Point earnings through the specified events will affect the customer's tier status.
    If the customer reaches the point limit of a higher tier with the newly earned points, they will be upgraded through the registration of a tier_up event.

  • Tier-down actions (optional)
    Point decreases caused by the specified events are taken into account when determining the customer's tier status. When left blank, no events will be considered.
    If the customer falls below the limit of their current tier based on the point deduction, they will be downgraded to the tier that they are eligible for through the registration of tier_down event.
    If the customer’s tier points value is reduced through a point_sub event, the number of tier points will be cut down points to maximum 0, even if the point deduction event would take away more than the customer's current tier points value.


Tier membership is calculated based on the amount of money customers spent in your offline locations and webstore.
If the customer reaches the spend limit of a higher tier after making a purchase, they will be upgraded through the registration of a tier_up event. If the customer returns item(s) and a refund event is submitted, the spend limit might fall below the threshold of the current tier. In this case, the customer is downgraded through the registration of a tier_down event according to the updated spend value.
If you handle multiple currencies in your loyalty program, the purchase currency will be converted into the base currency. The tier thresholds are set in base currency.


Invitation-only tiers can either be joined by the administrators of the Backoffice or by workflows set up in the Workflow editor.

Expiration logic

Please note that expiration is only available for point-based and spend-based types of tiers.

No expiration


Customer tier statuses expire after a specified number of months unless they keep collecting points or spending money that makes them stay in their current tier.

  • Expire after
    Set the recurrence of tier expiration in the ‘Expire after’ field. The recurrence can be set in monthly steps.


Tiers expire on a specific calendar day every year for each customer.

  • Set the date by defining the day and month of the expiration
    Multiple expiration dates can be added per year by clicking the ‘+ Add expiration date’ button. Upon tier status change, the next closest expiration date will be assigned to the customer’s new tier.
    Please note, that if you make changes to the configured expiration dates, the customers' tier expiration dates will not be updated automatically, the new expiration date is only assigned when customers enter a new tier within the structure.

  • Cross-tier membership refund handling
    If the checkbox is enabled and a checkout made before the last calendar expiration date is refunded the tier points are not deducted. This way the refund of transactions made in previous periods will not affect the customer’s current tier status and progress in the tier structure.

  • The ‘Tier membership should be at least ___ months old to be evaluated’ field lets you define the time after the last tier upgrade while no tier expiration would occur.
    This option lets customers keep the recently earned tier status if the next expiration date comes shortly after they have entered a new tier (eg. if there’s a 1-month grace period configured in this field and the next expiration date is 1 July, the customer who is tiered up to a higher tier on 14 June will not lose the tier, tier expiration will not occur on 1 July).


Tier expiration occurs once every year for each customer, on the date stored in any date type of customer attribute added under the Customers settings page.
This expiration is not available for Invitation-only tiers.

  • Select the customer attribute that should define the anniversary date using the dropdown menu
    This can be any custom field that requires a date or datetime-type field.
    The opt-in date is automatically applied as the customer’s date of points anniversary if the selected customer attribute is empty and the field doesn’t contain a date/datetime value.


If you introduce Rolling-, Calendar- or Anniversary-type expiration, the tier expiration date is always calculated starting from the date of entering the tier through the tier_up or tier_down event. The points collected/amount spent on the entry day is included in the tier calculation on the next tier expiration day.

The built-in points_after_expiration customer field stores the number of tier points customers would have after the next tier expiration date. This field is applicable in workflows, exports, and all customer filter options across the Backoffice. The value is also accessible through the Customer API.

There is a manual ‘Change tier expiration date' option available under the customer’s profile settings in the upper right corner, operated by the tier_change event.
Please note, that this manual tier expiration date is automatically recalculated when the next customer action is registered based on the configured expiration logic.

Expiration method

You can select the expiration method from 4 options:

  • The customer is downgraded to the tier level they have collected enough status points (points earned or money spent)
    The customer will keep the highest tier they have reached in the previous period, until the next expiration date. Status points are not reset, therefore customers can continue collecting points to achieve the next tier.

  • The customer is downgraded to the previous tier, regardless of the number of points collected or money spent in the given period.

  • If the current tier's threshold is not met, the customer will be automatically downgraded by one level in the tier structure.

  • Keep the highest reached tier level with a point reset
    Available for calendar and anniversary expiration only.
    The customer will keep the highest tier they have reached in the previous period, until the next expiration date, however, status points are reset which means that customers start the point collection to reach higher tiers from 0 points.

It may happen that you’d like to manually modify the customer’s tiers through the Tier up and Tier down options under the Customer insights menu.

If you use the Keep the highest reached tier level expiration method, customers cannot be manually downgraded to a tier lower than the one they qualify for based on the number of tier points they've collected.

Initialization upon opt-in

This option is only available for spend-based tiers.

If enabled, spend-based tier structures will automatically be initialized for customers when they are registered in the loyalty program.

Downgrade option

The checkbox is marked by default when creating a new tier structure.

By unchecking this box, you can protect the customer from being downgraded until the next tier expiration date, irrespective of the events or point balance changes that would lead to a tier downgrade. If unchecked, only these two processes can downgrade the tier:

Grace period for tier points

Enter here the preferred number of grace period days for the tier points. This field is optional.

The grace period applied on the point/spend amount carries the points over to the next cycle, provided they were collected within a predetermined time period from the expiration date.

Tier level grace period

Enter here the preferred number of grace period days for the tiers. This field is optional.

The tier grace period ensures that no tier expiration will occur if a customer has been upgraded to a higher tier within a predefined time period from the expiration date.

Tier configuration

Under ‘Tiers’, you can define the tiers within the tier structure. You can add an unlimited number of tiers to a tier structure.

  • Click the ‘Add tier’ button

  • ID
    Machine-readable ID of the tier structure that can be used to refer to the tier structure in the Antavo APIs.

  • Name
    The human-readable name of the tier structure, which is the displayed name of the tier in the Antavo Backoffice and is accessible through the API as well.
    If you have the Multilanguage module enabled in the loyalty program, you can use the ‘Translate’ button to add the name of the tier in each language. All translations can be accessed via API.

  • Threshold

    • Spend-based tier structures
      The amount that customers must spend to enter the tier. The threshold defines the limit to reach in the base currency. Additional currency spending is converted into the base currency to be able to be sorted into tiers.

    • Point-based tier structure
      The number of points customers have earned with actions completed in the loyalty program (known as score). If points are subtracted from the score after they were added, the customer might be downgraded to a lower tier if they don’t hit the threshold with the updated score value if the Downgrade option is enabled.

Points economy

If you use the Multiaccounts module in the loyalty program, you can attach point-based and spend-based tier structures to specific accounts. The customer’s status in this tier structure will be calculated based on the points balance or spend amount changes of the selected account.
Use the ‘Account’ dropdown field at the bottom of the editor page to select the account.

  • Don't forget to click ‘Save’ before leaving the page

Activate a tier structure

After saving for the first time, the status of the tier structure is ‘inactive’, which means that no customer can be assigned and it appears only in the list of Tier structures on the Tiers module configuration page.
You can activate the tier structure right away using the ‘Set active’ button on the upper right-hand side of the setup page and confirm the activation in the dialog that subsequently appears.

Managing tier structures

Edit a tier structure

  • Go to the Tiers management page

  • Click the ‘Edit’ button of the tier structure you want to edit

  • Edit your tier structure

  • Save your changes by clicking ‘Update’

Deactivate a tier structure

If you choose to remove the tier structure from the membership site, you can deactivate it anytime:

  • Go to the Tiers management page

  • Click the ‘Edit’ button of the tier structure you want to edit

  • Click on the ‘Set inactive’ button on the upper right-hand side of the page

  • Confirm your choice in the dialog that appears

Inactive tier structures are not included in the response when requesting tier structures via API.

Archive a tier structure

You have the option to delete inactive structures from the Backoffice by archiving them.

  • Go to the Tiers management page

  • Click on the inactive structure you want to archive

  • Click on the ‘Archive’ button on the upper right-hand side of the page

  • Confirm your choice in the dialog that appears

Archiving is irreversible. Once a tier structure is archived, it cannot be restored anymore.

Filter tier structures

You can filter your tier structures in the Backoffice by clicking on the ‘Filters’ button at the top of the Tier management page. There are three options: filter by status, type, or both. Click ‘Apply’ to see the filtered list, or ‘Reset’ to choose a new filtering method.

Manual tier upgrade and downgrade mechanisms

There are two ways in which manual tier upgrades or downgrades can occur:

  • You can adjust a customer's tier directly within the customer's profile, using the Customer Insights module in the Backoffice

    • Follow these steps to perform manual up/downgrade:

      • Go to the Customer’s profile. You can manage basic profile actions in the upper right corner.

      • If the Tier up/down buttons do not appear, you can access the additional options by selecting the 'More' hamburger icon.

      • A popup window will appear with two dropdowns:

        • Selectable tier structure

        • Selectable tier status to which you would like the upgrade/downgrade to happen.

      • Click ‘Set tier’.

  • tier_up and tier_down events can be triggered by a workflow that is set up to respond to certain events

Manual tier upgrade process specifics

The manual tier upgrades are represented by the manual attribute in the tier_up event in both cases (i.e., administrator AND workflow-driven upgrades).

Once the tier is manually upgraded, then the customer's tier level is set, even if subsequent actions may put them in a lower tier. Downgrading can only occur if there is a tier expiration.

However, a downgrade can still occur if the point deduction still places the customer in a higher tier than the manually set one.


© Copyright 2022 Antavo Ltd.