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.
Did this help?

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.


tierDefinitionTierDefinition

Information about the tier.


requiredPointsintegerminimum 0maximum 9999999

The amount of points required to be in this tier.


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.

Tier
JSON
{ "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "" }, "requiredPoints": 200, "revision": "2", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" }
Did this help?

GET

List Tiers


Retrieves a list of a site's tiers.

To retrieve a specific tier, use Get Tier.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers

Request
This endpoint does not take any parameters.
Response Object
tiersArray <Tier>

Retrieved loyalty tiers.

List tiers
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "tiers": [ { "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 200, "revision": "1", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" } ] }
Did this help?

POST

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

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/tiers

Body Params
tierTierRequired

Tier to create.

Response Object
tierTier

Created loyalty tier.

Create tier
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "tier": { "tierDefinition": { "name": "Gold", "description": "Earn 2x points and get special discount", "icon": { "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg" } }, "requiredPoints": 200 } }'
Response
JSON
{ "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 200, "revision": "1", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" }
Event TriggersThis method triggers the following events:
Did this help?

POST

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

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/bulk/tiers/create

Body Params
tiersArray <Tier>minItems 1maxItems 20

Tiers to create.

Response Object
resultsArray <BulkTierResult>

Created tiers.


bulkActionMetadataBulkActionMetadata

Bulk action metadata.

Bulk create tiers
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-tiers/v1/bulk/tiers/create' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "tiers": [ { "tierDefinition": { "name": "Gold", "description": "Earn 2x points and get special discount", "icon": { "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg" } }, "requiredPoints": 200 } ] }'
Response
JSON
{ "results": [ { "item": { "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 200, "revision": "1", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" }, "itemMetadata": { "id": "d7dfacd5-8141-456b-b278-6383b97f2569", "originalIndex": 0, "success": true, "error": null } } ], "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0, "undetailedFailures": 0 } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Tier


Retrieves a loyalty tier.

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

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tierId}

Path Params
tierIdstringRequired

ID of the tier to retrieve.

Response Object
tierTier

Retrieved loyalty tier.

Get tier
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/acddc0e0-5e27-4a1b-a52d-b3785ac258cb' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 200, "revision": "1", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" }
Did this help?

DELETE

Delete Tier


Deletes a loyalty tier.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tierId}

Path Params
tierIdstringRequired

ID of the tier to delete.

Query Params
revisionnumber

Current revision of the tier to delete.

Response Object
Returns an empty object.
Create tier
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/acddc0e0-5e27-4a1b-a52d-b3785ac258cb?revision=1' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Tier


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/loyalty-tiers/v1/tiers/{tier.id}

Path Params
tier.idstringRequired

Tier ID.

Body Params
tierTierRequired

Tier details to update.

Response Object
tierTier

Updated loyalty tier.

Update tier
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/acddc0e0-5e27-4a1b-a52d-b3785ac258cb' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "tier": { "tierDefinition": { "name": "Gold", "description": "Earn 2x points and get special discount", "icon": { "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg" } }, "requiredPoints": 400 } }'
Response
JSON
{ "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 400, "revision": "2", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Tiers Program Settings


Retrieves the settings for the tiers program.

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

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings

Request
This endpoint does not take any parameters.
Response Object
programSettingsProgramSettings

Tiers program settings.

Get tiers program settings
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings \ -H 'Authorization: <AUTH>'
Response
JSON
{ "programSettings": { "status": "ACTIVE", "revision": "3", "createdDate": "2024-02-09T09:06:21.823Z", "updatedDate": "2024-04-17T14:23:22.985Z", "baseTierDefinition": { "icon": { "id": "", "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg", "height": 0, "width": 0 }, "name": "Basic", "description": "Basic tier" }, "rollingWindow": { "durationInMonths": 12 } } }
Did this help?

POST

Create Tiers Program Settings


Create tiers program settings.

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings

Body Params
programSettingsProgramSettingsRequired

Tiers program settings.

Response Object
programSettingsProgramSettings

Created tiers program settings.

Create tiers program settings
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "programSettings": { "status": "ACTIVE", "baseTierDefinition": { "name": "Basic", "description": "Basic tier", "icon": { "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg" } }, "rollingWindow": { "durationInMonths": 12 } } }'
Response
JSON
{ "programSettings": { "status": "ACTIVE", "revision": "1", "createdDate": "2024-02-09T09:06:21.823Z", "updatedDate": "2024-04-17T14:23:22.985Z", "baseTierDefinition": { "icon": { "id": "", "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg", "height": 0, "width": 0 }, "name": "Basic", "description": "Basic tier" }, "rollingWindow": { "durationInMonths": 12 } } }
Did this help?

PATCH

Update Tiers Program Settings


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings

Body Params
programSettingsProgramSettingsRequired

Settings for the tiers program.

Response Object
programSettingsProgramSettings

Updated program settings.

Update tiers program settings
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "programSettings": { "status": "PAUSED", "revision": "1", "baseTierDefinition": { "name": "Basic", "description": "Basic tier", "icon": { "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg" } }, "rollingWindow": { "durationInMonths": 12 } } }'
Response
JSON
{ "programSettings": { "status": "PAUSED", "revision": "2", "createdDate": "2024-02-09T09:06:21.823Z", "updatedDate": "2024-04-17T14:23:22.985Z", "baseTierDefinition": { "icon": { "id": "", "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg", "height": 0, "width": 0 }, "name": "Basic", "description": "Basic tier" }, "rollingWindow": { "durationInMonths": 12 } } }
Did this help?

GET

Get Tiers Program


Returns Tiers and ProgramSettings in a single response.

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

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-tiers/v1/tiers/program

Request
This endpoint does not take any parameters.
Response Object
tiersArray <Tier>

Tiers.


programSettingsProgramSettings

Tiers program settings.

Get tiers program
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-tiers/v1/tiers/program \ -H 'Authorization: <AUTH>'
Response
JSON
{ "tiers": [ { "id": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb", "tierDefinition": { "icon": { "id": "", "url": "shapes/39dce0a5d1ce498f95526b1390eaf585.svg", "height": 0, "width": 0 }, "name": "Gold", "description": "Earn 2x points and get special discount" }, "requiredPoints": 200, "revision": "2", "createdDate": "2024-02-15T14:22:02.539Z", "updatedDate": "2024-04-17T11:34:25.274Z" } ], "programSettings": { "status": "ACTIVE", "revision": "3", "createdDate": "2024-02-09T09:06:21.823Z", "updatedDate": "2024-04-17T14:23:22.985Z", "baseTierDefinition": { "icon": { "id": "", "url": "shapes/11062b_0a8e17936d5b4d46971649be036c781b.svg", "height": 0, "width": 0 }, "name": "Basic", "description": "Basic tier" }, "rollingWindow": { "durationInMonths": 12 } } }
Did this help?

Tier Created


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.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.loyalty.v1.tier_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?

Tier Updated


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.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.loyalty.v1.tier_updated", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?

Tier Deleted


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.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.loyalty.v1.tier_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?