Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

tiers

Creates up to 20 tiers.

The name for a tier and the amount of required points to qualify for a tier can only exist for a single tier.
Attempts to create a tier with a `tierDefinition.name` or `requiredPoints` that already exists will return an error.

To create a single tier, use [`createTier()`](#createtier).

>**Note:** You must have a [Business VIP Premium plan](https://support.wix.com/en/article/business-vip-premium-plan-overview) or a [Scale Premium plan](https://support.wix.com/en/article/editor-x-scale-premium-plan-overview) to add tiers.

import { tiers } from 'wix-loyalty.v2';

async function bulkCreateTiers(tiers) {
  try {
    const result = await tiers.bulkCreateTiers(tiers);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


bulkCreateTiers example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedBulkCreateTiers = elevate(tiers.bulkCreateTiers);

export const bulkCreateTiers = webMethod(
  Permissions.Anyone,
  async (tiers) => {
    try {
      const result = await elevatedBulkCreateTiers(tiers);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


bulkCreateTiers example for exporting from backend code

bulkCreateTiers

BulkCreateTiersResponse

tier

Tier

Creates a tier.

The name for a tier and the amount of required points to qualify for a tier can only exist for a single tier.
Attempts to create a tier with a `tierDefinition.name` or `requiredPoints` that already exists will return an error.

To create up to 20 tiers at once, use [`bulkCreateTiers()`](#bulkcreatetiers).

>**Note:** You must have a [Business VIP Premium plan](https://support.wix.com/en/article/business-vip-premium-plan-overview) or a [Scale Premium plan](https://support.wix.com/en/article/editor-x-scale-premium-plan-overview) to add tiers.

import { tiers } from 'wix-loyalty.v2';

async function createTier(tier) {
  try {
    const result = await tiers.createTier(tier);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


createTier example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedCreateTier = elevate(tiers.createTier);

export const createTier = webMethod(
  Permissions.Anyone,
  async (tier) => {
    try {
      const result = await elevatedCreateTier(tier);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


createTier example for exporting from backend code

createTier

programSettings

TiersProgramSettings

Create tiers program settings.

Tiers program settings apply globally to all tiers in the program.

import { tiers } from 'wix-loyalty.v2';

async function createTiersProgramSettings(programSettings) {
  try {
    const result = await tiers.createTiersProgramSettings(programSettings);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


createTiersProgramSettings example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedCreateTiersProgramSettings = elevate(tiers.createTiersProgramSettings);

export const createTiersProgramSettings = webMethod(
  Permissions.Anyone,
  async (programSettings) => {
    try {
      const result = await elevatedCreateTiersProgramSettings(programSettings);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


createTiersProgramSettings example for exporting from backend code

createTiersProgramSettings

CreateTiersProgramSettingsResponse

tierId

string

Current `revision` of the tier to delete.

revision

import { tiers } from 'wix-loyalty.v2';

async function deleteTier(tierId, revision) {
  try {
    const result = await tiers.deleteTier(tierId, revision);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


deleteTier example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedDeleteTier = elevate(tiers.deleteTier);

export const deleteTier = webMethod(
  Permissions.Anyone,
  async (tierId, revision) => {
    try {
      const result = await elevatedDeleteTier(tierId, revision);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


deleteTier example for exporting from backend code

deleteTier

void

Retrieves a loyalty tier.

To retrieve a list of all of a site's tiers, use [`listTiers()`](#listtiers).

import { tiers } from 'wix-loyalty.v2';

async function getTier(tierId) {
  try {
    const result = await tiers.getTier(tierId);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


getTier example

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';

export const getTier = webMethod(
  Permissions.Anyone,
  async (tierId) => {
    try {
      const result = await tiers.getTier(tierId);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


getTier example for exporting from backend code

getTier

Returns `Tiers` and `ProgramSettings` in a single response.

If `TiersProgramSettings` doesn't exist, default `TiersProgramSettings` are created.

import { tiers } from 'wix-loyalty.v2';

async function getTiersProgram() {
  try {
    const result = await tiers.getTiersProgram();
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


getTiersProgram example

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';

export const getTiersProgram = webMethod(
  Permissions.Anyone,
  async () => {
    try {
      const result = await tiers.getTiersProgram();
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


getTiersProgram example for exporting from backend code

getTiersProgram

GetTiersProgramResponse

Retrieves the settings for the tiers program.

Tiers program settings apply globally to all tiers in the program.

import { tier } from 'wix-loyalty-backend';

export async function myGetProgramSettingsFunction() {
  try {
    const tiersProgramSettings = await tier.getTiersProgramSettings();

    const status = tiersProgramSettings.programSettings.status;
    const revision = tiersProgramSettings.programSettings.revision;

    console.log('Success! Current status of tiers program: ', status);
    return tiersProgramSettings;
  } catch (error) {
    console.error(error);
  }
}

Get tiers program settings

import { Permissions, webMethod } from 'wix-web-module';
import { tier } from 'wix-loyalty.v2';

export const myGetProgramSettingsFunction = webMethod(Permissions.Anyone, async () => {
  try {
    const tiersProgramSettings = await tier.getTiersProgramSettings();

    const status = tiersProgramSettings.programSettings.status;
    const revision = tiersProgramSettings.programSettings.revision;

    console.log('Success! Current status of tiers program: ', status);
    return tiersProgramSettings;
  } catch (error) {
    console.error(error);
  }
});


Get tiers program settings (export from backend code)

getTiersProgramSettings

GetTiersProgramSettingsResponse

Retrieves a list of a site's tiers.

To retrieve a specific tier, use [`getTier()`](#gettier).

import { tier } from 'wix-loyalty-backend';

export async function myListTiersFunction() {
  try {
    const tiersList = await tier.listTiers();

    const firstTierId = tiersList.tiers[0]._id;
    const firstTierPointsRequired = tiersList.tiers[0].requiredPoints;

    console.log('Success! First tier ID: ', firstTierId, ' requires ', firstTierPointsRequired, ' points.');
    return tiersList;
  } catch (error) {
    console.error(error);
  }
}

Get a list of loyalty tiers

import { Permissions, webMethod } from 'wix-web-module';
import { tier } from 'wix-loyalty.v2';

export const myListTiersFunction = webMethod(Permissions.Anyone, async () => {
  try {
    const tiersList = await tier.listTiers();

    const firstTierId = tiersList.tiers[0]._id;
    const firstTierPointsRequired = tiersList.tiers[0].requiredPoints;

    console.log('Success! First tier ID: ', firstTierId, ' requires ', firstTierPointsRequired, ' points.');
    return tiersList;
  } catch (error) {
    console.error(error);
  }
});


Get a list of loyalty tiers (export from backend code)

listTiers

ListTiersResponse

UpdateTier

Updates a loyalty tier.

Use this endpoint to update tier-specific settings, such as the name and the required points
threshold of an individual loyalty tier. To update global settings that apply to all of a site's loyalty tiers,
use [`updateTiersProgramSettings()`](#updatetiersprogramsettings).

import { tiers } from 'wix-loyalty.v2';

async function updateTier(id, tier) {
  try {
    const result = await tiers.updateTier(id, tier);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


updateTier example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedUpdateTier = elevate(tiers.updateTier);

export const updateTier = webMethod(
  Permissions.Anyone,
  async (id, tier) => {
    try {
      const result = await elevatedUpdateTier(id, tier);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


updateTier example for exporting from backend code

updateTier

Updates the global settings of a loyalty tier program.

Use this endpoint to update settings that apply to all of a site's loyalty tiers.
To update tier-specific settings for an individual tier, use
[`updateTier()`](#updatetier).

By default, the `status` of a tiers program is set to `"DISABLED"` and must be manually updated to `"ACTIVE"` using
this endpoint or through a site owner's [dashboard](https://manage.wix.com/account/site-selector/?actionUrl=https%3A%2F%2Fwww.wix.com%2Fdashboard%2F%7BmetaSiteId%7D%2Floyalty-accounts%2Fmanage%3Ftab%3Dpoints-and-rewards&title=Select+a+Site&primaryButtonText=Select+Site).

>**Note:** The `status`, `revision`, and `rollingWindow` parameters must be passed to update the tiers program settings. The `baseTierDefinition` fields are not required, however, if you don't pass them they will reset to their default values of empty fields.

import { tiers } from 'wix-loyalty.v2';

async function updateTiersProgramSettings(programSettings) {
  try {
    const result = await tiers.updateTiersProgramSettings(programSettings);
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


updateTiersProgramSettings example for dashboard page code

import { tiers } from 'wix-loyalty.v2';
import { webMethod, Permissions } from 'wix-web-module';
import { elevate } from 'wix-auth';

const elevatedUpdateTiersProgramSettings = elevate(tiers.updateTiersProgramSettings);

export const updateTiersProgramSettings = webMethod(
  Permissions.Anyone,
  async (programSettings) => {
    try {
      const result = await elevatedUpdateTiersProgramSettings(programSettings);
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


updateTiersProgramSettings example for exporting from backend code

updateTiersProgramSettings

UpdateTiersProgramSettingsResponse

---
title: Introduction
---

# Introduction
&nbsp;
<div style="background-color: #FEF1D1; padding: 18px 24px; border-radius: 6px; border: 1px solid #FDB10C; box-sizing: border-box; display: inline-block">
    <b>Developer Preview</b>
    <br/>
    <span>APIs in <a href="https://www.wix.com/velo/reference/api-overview/developer-preview">Developer Preview</a> are subject to change and are not intended for use in production.<br/><a href="mailto:velo-preview-feedback@wix.com">Send us</a> your suggestions for improving this API. Your feedback is valuable to us.</span>
</div>  

&nbsp;

The Loyalty Tiers API allows you to create a levels-based program that assigns loyalty accounts to different tiers based on the amount of points they have earned.  

With the Loyalty Tiers API, you can:
- [Create](#createtier) and [update](#updatetier) individual tiers.
- [Update](#updatetiersprogramsettings) settings that apply globally to the tiers program.  

For more information about loyalty tiers, see [Adding Tiers to Your Loyalty Program](https://support.wix.com/en/article/wix-loyalty-program-adding-tiers-to-your-loyalty-program).  

To use the Loyalty Tiers API, import `{ tiers }` from the `wix-loyalty.v2` module. 

```javascript
import { tiers } from 'wix-loyalty.v2';
```

## Before you begin  

It's important to note the following points before starting to code:
- The site must have a [Business VIP Premium Plan](https://support.wix.com/en/article/business-vip-premium-plan-overview) or a [Scale Premium Plan](https://support.wix.com/en/article/editor-x-scale-premium-plan-overview) to add tiers.
- The site must have at least one of these apps: Wix Bookings, Wix Events, Wix Pricing Plans, or Wix Stores.
  >**Note:** Currently, tiers cannot be added to Wix Restaurants loyalty programs.
- The tiers program `status` must be manually set to `ACTIVE`. Use [`updateTiersProgramSettings()`](#updatetiersprogramsettings) to update the `status` or enable tiers from a site owner's [dashboard](https://manage.wix.com/account/site-selector/?actionUrl=https%3A%2F%2Fwww.wix.com%2Fdashboard%2F%7BmetaSiteId%7D%2Floyalty-accounts%2Fmanage%3Ftab%3Dpoints-and-rewards&title=Select+a+Site&primaryButtonText=Select+Site).
- The Loyalty Tiers API does not handle rules for earning points based on your tier. A site owner may adjust those settings from their dashboard. See [Assign ways to earn to each tier](https://support.wix.com/en/article/wix-loyalty-program-adding-tiers-to-your-loyalty-program#step-2-assign-ways-to-earn-and-rewards-to-each-tier).

## Terminology  

- **Tiers program settings:** Settings that apply globally to the overall tiers program.  
- **Base tier:** A default tier for any loyalty account that is unassigned for not meeting the required points threshold of any other tier. The base tier requires `0` points, has no `tierId`, and is not returned as a tier when [`listTiers()`](#listtiers) is called. When a tiers program status is `PAUSED` or `DISABLED` all of the loyalty accounts are assigned to the base tier.
- **Rolling window:** Period of time used to calculate loyalty points for tier assignment. The total points earned and adjusted during this period determine if the account meets a tier's required point threshold. The window is recalculated every 15 minutes or if a new tier event triggers.
- **Points earned and adjusted:** Tier assignment is based on the total amount of loyalty points earned and adjusted over the period of time in a `rollingWindow`. If an account redeems points during that period, the points that were earned still count towards tier assignment even if that leaves the remaining points balance below the tier's required point threshold. Similarly, if the current points balance for a loyalty account is above a tier's required points threshold, but those points were earned in a time period earlier than the `rollingWindow` then those points are not considered for tier assignment.

velo-deps_wix-loyalty.v2_tiers

ApplicationError

code

data

description

BulkActionMetadata

Number of items that couldn't be processed.

totalFailures

number

Number of items that were successfully processed.

totalSuccesses

Number of failures without details because detailed failure threshold was exceeded.

undetailedFailures

bulkActionMetadata

results

BulkTierResult

item

itemMetadata

ItemMetadata

Item ID. Should always be available, unless it's impossible (for example, when failing to create an item).

Details about the error in case of failure.

error

Index of the item within the request array. Allows for correlation between request and response items.

originalIndex

Whether the requested action was successful for this item. When `false`, the `error` field is populated.

success

boolean

RollingWindow

Number of months to use for the rolling window period.

Min: `12`

Max: `36`

durationInMonths

Status

_createdDate

_updatedDate

The amount of points required to be in this tier.

requiredPoints

Revision number, which increments by 1 each time the loyalty tier is updated.

To prevent conflicting changes, the current `revision` must be passed when updating the loyalty tier.

tierDefinition

TierDefinition

icon

name

*Required.**
Period of time used to calculate loyalty points for tier assignment.

The loyalty points accumulated during this period determine if the account meets a tier's required point threshold.

rollingWindow

Date and time the loyalty tiers program was created.

Date and time the loyalty tiers program was last updated.

Information about the base loyalty tier.

The base tier is the default tier for any account that is unassigned for not meeting
the required points threshold of any other tier.

baseTierDefinition

Revision number, which increments by 1 each time the loyalty tiers settings are updated.

To prevent conflicting changes, the current `revision` must be passed when updating the loyalty tiers settings.

listTiers( )

Permission Scopes