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:
For more information about loyalty tiers, see Adding Tiers to Your Loyalty Program.
It's important to note the following points before starting to code:
Note: Currently, tiers cannot be added to Wix Restaurants loyalty programs.
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.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.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.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.
Tier ID.
Information about the tier.
The amount of points required to be in this tier.
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.
Date and time the tier was created.
Date and time the tier was last updated.
{
"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"
}
Retrieves a list of a site's tiers.
To retrieve a specific tier, use Get Tier.
Retrieved loyalty tiers.
curl -X GET \
'https://www.wixapis.com/loyalty-tiers/v1/tiers' \
-H 'Authorization: <AUTH>'
{
"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"
}
]
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tier to create.
Created loyalty tier.
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
}
}'
{
"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"
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tiers to create.
Created tiers.
Bulk action metadata.
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
}
]
}'
{
"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
}
}
Retrieves a loyalty tier.
To retrieve a list of all of a site's tiers, use List Tiers.
ID of the tier to retrieve.
Retrieved loyalty tier.
curl -X GET \
'https://www.wixapis.com/loyalty-tiers/v1/tiers/acddc0e0-5e27-4a1b-a52d-b3785ac258cb' \
-H 'Authorization: <AUTH>'
{
"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"
}
Deletes a loyalty tier.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the tier to delete.
Current revision
of the tier to delete.
curl -X DELETE \
'https://www.wixapis.com/loyalty-tiers/v1/tiers/acddc0e0-5e27-4a1b-a52d-b3785ac258cb?revision=1' \
-H 'Authorization: <AUTH>'
{}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tier ID.
Tier details to update.
Updated loyalty tier.
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
}
}'
{
"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"
}
Retrieves the settings for the tiers program.
Tiers program settings apply globally to all tiers in the program.
Tiers program settings.
curl -X GET \
'https://www.wixapis.com/loyalty-tiers/v1/tiers/program-settings \
-H 'Authorization: <AUTH>'
{
"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
}
}
}
Create tiers program settings.
Tiers program settings apply globally to all tiers in the program.
You can only call this method when authenticated as a Wix app or Wix user identity.
Tiers program settings.
Created tiers program settings.
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
}
}
}'
{
"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
}
}
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Settings for the tiers program.
Updated program settings.
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
}
}
}'
{
"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
}
}
}
Returns Tiers
and ProgramSettings
in a single response.
If TiersProgramSettings
doesn't exist, default TiersProgramSettings
are created.
Tiers.
Tiers program settings.
curl -X GET \
'https://www.wixapis.com/loyalty-tiers/v1/tiers/program \
-H 'Authorization: <AUTH>'
{
"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
}
}
}
Triggered when a tier has been created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"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
}
}
}
Triggered when a tier is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"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
}
}
}
Triggered when a tier is deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.tier
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"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
}
}
}