Introduction

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 and update individual tiers.
  • Update settings that apply globally to the tiers program.

For more information about loyalty tiers, see Adding Tiers to Your Loyalty Program.

Before you begin

It's important to note the following points before starting to code:

  • The site must have a Business VIP Premium Plan or a Scale Premium Plan 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 Update Tiers Program Settings to update the status or enable tiers from a site owner's dashboard.
  • 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.

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 List Tiers 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.
Was this helpful?
Yes
No
Tier Object

A tier is a loyalty level that customers are assigned to based on the amount of points they earn. Read more about loyalty tiers here.

Properties
idstringRead-onlyformat GUID
Tier ID.
tierDefinitionobject
Information about the tier.
requiredPointsintegerminimum 0maximum 9999999
The amount of points required to be in this tier. Min: "0" Max: "9999999"
revisionintegerRead-onlyformat uint64
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.
createdDatestringRead-onlyformat date-time
Date and time the tier was created.
updatedDatestringRead-onlyformat date-time
Date and time the tier was last updated.
Was this helpful?
Yes
No
PostCreate Tier
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 Bulk Create Tiers.

Note: You must have a Business VIP Premium plan or a Scale Premium plan to add tiers.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Loyalty
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/tiers
Event TriggersThis method triggers the following events:
Tier Created
Was this helpful?
Yes
No
PostBulk Create Tiers
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 Create Tier.

Note: You must have a Business VIP Premium plan or a Scale Premium plan to add tiers.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Loyalty
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/bulk/tiers/create
Event TriggersThis method triggers the following events:
Tier Created
Was this helpful?
Yes
No
GetGet Tier
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a loyalty tier.

To retrieve a list of all of a site's tiers, use List Tiers.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Loyalty
Manage Loyalty
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tierId}
Was this helpful?
Yes
No
DeleteDelete Tier
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a loyalty tier.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Loyalty
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tierId}
Event TriggersThis method triggers the following events:
Tier Deleted
Was this helpful?
Yes
No
PatchUpdate Tier
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 Update Tiers Program Settings.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Loyalty
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tier.id}
Event TriggersThis method triggers the following events:
Tier Updated
Was this helpful?
Yes
No
PostList Tiers
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of a site's tiers.

To retrieve a specific tier, use Get Tier.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Loyalty
Manage Loyalty
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/tiers/query
Was this helpful?
Yes
No
GetGet Tiers Program Settings
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the settings for the tiers program.

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

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Loyalty
Manage Loyalty
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings
Was this helpful?
Yes
No
PatchUpdate Tiers Program Settings
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 Update Tier.

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.

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.

Note: This endpoint requires visitor or member authentication.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Loyalty
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings
Was this helpful?
Yes
No
Tier Created
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a tier has been created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier.
slugstring
Event name. Expected created.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
createdEventobject
Event information.
Was this helpful?
Yes
No
Tier Updated
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a tier is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier.
slugstring
Event name. Expected updated.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
updatedEventobject
Event information.
Was this helpful?
Yes
No
Tier Deleted
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a tier is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier.
slugstring
Event name. Expected deleted.
entityIdstring
ID of the entity associated with the event.
eventTimestringformat date-time
Event timestamp.
triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
originatedFromstring
If present, indicates the action that triggered the event.
deletedEventstruct
Event information.
Was this helpful?
Yes
No