The Earning Rules API allows you to manage earning rules for your loyalty program. Earning rules define how customers earn points through various activities, such as making purchases or registering for events.
With the Earning Rules API, you can:
For more information about managing loyalty programs, see the Loyalty API. To learn more about earning rules, see Managing Your Loyalty Program.
An earning rule defines how customers receive loyalty points for specific actions they take on your site, such as making a purchase or booking an appointment. Customers accumulate these loyalty points and can later exchange them for rewards like discounts or free shipping at checkout.
Earning rules use two methods to calculate loyalty points:
Fixed amount: Awards a set number of points for a specific action. Example: A customer receives 10 points for purchasing a ticket through Wix Events.
Conversion rate: Awards points based on a ratio of money spent to points earned. Example: A customer receives 2 points for every $1 spent in your online store.
The formula is: points awarded = (amount spent / moneyAmount) * points per unit
.
For a $100 purchase with 2 points awarded per $1 spent:
points awarded = (100 / 1) * 2 = 200 points
Once customers accumulate loyalty points, they can redeem them for various rewards during the checkout process. For example, exchanging 500 points for a 10% discount on their purchase.
The Wix Loyalty program supports two types of earning rules:
Both types allow customers to earn points for various actions, but differ in their flexibility and customization options:
We recommend creating automated earning rules using the Wix Automations API for maximum flexibility and customization options.
Automated earning rules are managed by Wix Automations, a system that enables custom workflows across Wix apps. These rules offer more flexibility and can be triggered by a wide range of events.
There are two subtypes of automated earning rules:
Pre-installed rules come automatically when certain business solutions are installed. These rules can be paused but not deleted.
Supported pre-installed earning rules:
Earning Rule Name | Trigger | Point award method |
---|---|---|
Order a plan (Wix Pricing Plans) | wix_pricing_plans-plan_purchased | Fixed amount, Conversion rate |
Place a restaurant order (Old Wix Restaurants) | wix_restaurants_orders-order_submitted | Conversion rate only |
Place a restaurant order (New Wix Restaurants) | restaurants-order-is-pending | Conversion rate only |
Custom rules are created by site owners and don't come pre-installed. Automated earning rules not listed above fall into this category.
For example, if Wix Bookings is installed, you can create a custom automated earning rule that is triggered when a customer books a session.
Non-automated earning rules can be created based on installed Wix business solutions. These rules are identified by their sourceAppId
, which is the Loyalty app ID for non-automated rules.
Supported non-automated earning rules:
Earning Rule Name | Trigger | Point award method |
---|---|---|
Purchase a product (Wix Stores) | stores/OrderPaid | Fixed amount, Conversion rate |
Book a session (Wix Bookings) | bookings/BookingConfirmed | Fixed amount only |
Buy a ticket (Wix Events) | events/OrderConfirmed | Fixed amount, Conversion rate |
RSVP to an event (Wix Events) | events/Rsvp | Fixed amount only |
For example, if Wix Events is installed, two types of earning rules can be created:
events/OrderConfirmed
).events/Rsvp
).These non-automated rules provide a way to set up basic loyalty rewards without the Wix automations setup. They are useful for implementing a straightforward points system based on common customer actions within Wix apps.
Automated earning rules are powered by Wix Automations, a system that enables custom workflows across Wix apps.
Wix Automations are built on two key concepts:
To create and manage automated earning rules, you'll use the Wix Automations API. This API allows you to define custom triggers, implement action logic, and activate automations.
For more information on working with Wix Automations, see the Automations API Introduction.
sourceAppId
.points awarded = (amount spent / moneyAmount) * points per unit
.auth/register
, events/OrderConfirmed
.sourceAppId
is the Loyalty app ID, it's a non-automated earning rule. If it's the Wix Automations app ID, it's an automated earning rule.ACTIVE
, PAUSED
).A loyalty earning rule defines how customers earn points in a loyalty program. You can create rules for different activities, such as making purchases.
Loyalty earning rule ID.
ID of the app managing the earning rule. Can be a loyalty app ID or a Wix automations app ID.
ID of the app that triggers point assignment. Examples: Wix Stores, Wix Bookings, Wix Events.
Type of activity that triggers point assignment. For example, wix-restaurants/orderSubmitted
or birthday
.
Name of the earning rule.
Current status of the earning rule.
Revision number, incremented by 1 each time the earning rule is updated. Pass the latest revision when updating to prevent conflicting changes.
Date and time the earning rule was created.
Date and time the earning rule was last updated.
Additional metadata about the earning rule.
Fixed amount of points awarded for each qualifying activity.
Points awarded based on a conversion rate formula: (amount spent) / (money_amount * points)
.
{
"id": "61f971c4-b33b-4f39-8ebe-2677bce55789",
"source_app_id": "139ef4fa-c108-8f9a-c7be-d5f492a2c939",
"trigger_app_id": "eb377299-86b4-4a86-a1b5-774a2d1d374b",
"trigger_activity_type": "wix_members-uou_signs_up",
"title": "Sign up to the site",
"status": "ACTIVE",
"revision": null,
"created_date": "2024-08-01T11:51:41.431Z",
"updated_date": "2024-09-16T12:03:00.434Z",
"metadata": {
"can_be_deleted": false
},
"fixed_amount": {
"points": 50,
"configs": [
{
"tier_id": null,
"points": 50
}
]
}
}
Creates a non-automated earning rule.
Note: You can only create non-automated earning rules from a supported list. For the supported list of services, see the introduction.
You can only call this method when authenticated as a Wix app or Wix user identity.
Earning rule to create.
Created earning rule.
curl -X POST \
'https://www.wixapis.com/loyalty-earning-rules/v1/earning-rules' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"earningRule": {
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"status": "ACTIVE",
"conversionRate": {
"configs": [
{
"points": 20,
"moneyAmount": 1
}
]
}
}
}'
{
"earningRule": {
"id": "b690f925-8527-4d5e-b358-4b0adcb275b5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:06:39.294Z",
"updatedDate": "2024-09-16T12:06:39.294Z",
"metadata": {
"canBeDeleted": true
}
}
}
Creates multiple non-automated earning rules.
Note: You can only create non-automated earning rules from a supported list. For the supported list of services, see the introduction.
You can only call this method when authenticated as a Wix app or Wix user identity.
Earning rules to create.
Created earning rules.
Additional metadata for the created earning rules.
curl -X POST \
'https://www.wixapis.com/loyalty-earning-rules/v1/bulk/earning-rules/create' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"earningRules": [
{
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"status": "ACTIVE",
"conversionRate": {
"configs": [
{
"points": 20,
"moneyAmount": 1
}
]
}
}
]
}'
{
"results": [
{
"itemMetadata": {
"id": "eeb9ff42-b24f-4a68-8491-21507508f3f5",
"originalIndex": 0,
"success": true
},
"item": {
"id": "eeb9ff42-b24f-4a68-8491-21507508f3f5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:12:16.833Z",
"updatedDate": "2024-09-16T12:12:16.833Z",
"metadata": {
"canBeDeleted": true
}
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 1,
"totalFailures": 0,
"undetailedFailures": 0
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a custom automated earning rule.
Currently, only social media earning rule is supported.
You can only call this method when authenticated as a Wix app or Wix user identity.
Type of the custom earning rule.
Custom earning rule to create.
Created earning rule.
Retrieves a specified non-automated earning rule.
To retrieve both automated and non-automated earning rules, use List Earning Rules.
ID of the earning rule to retrieve.
Retrieved earning rule.
curl -X GET \
'https://www.wixapis.com/loyalty-earning-rules/v1/earning-rules/eeb9ff42-b24f-4a68-8491-21507508f3f5' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{
"earningRule": {
"id": "eeb9ff42-b24f-4a68-8491-21507508f3f5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:12:16.833Z",
"updatedDate": "2024-09-16T12:12:16.833Z",
"metadata": {
"canBeDeleted": true
}
}
}
Deletes a non-automated earning rule.
To delete an automated earning rule, use Delete Automation Earning Rule.
To update an earning rule's status instead of deleting it, use Update Loyalty Earning Rule.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the earning rule to delete.
Revision of the earning rule. Incremented by 1 each time the earning rule is updated. Pass the latest revision when updating to prevent conflicting changes.
curl -X DELETE \
'https://www.wixapis.com/loyalty-earning-rules/v1/earning-rules/eeb9ff42-b24f-4a68-8491-21507508f3f5?revision=2' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{}
Deletes a custom automated earning rule. Pre-installed automated rules can only be paused, not deleted.
To update an earning rule's status instead of deleting it, use Update Loyalty Earning Rule.
To delete a non-automated earning rule, use Delete Loyalty Earning Rule.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the earning rule to delete.
curl -X DELETE \
'https://www.wixapis.com/loyalty-earning-rules/v1/automation-earning-rules/61f971c4-b33b-4f39-8ebe-2677bce55789' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{}
Updates an earning rule.
Supports partial updates.
Revision number, which increments by 1 each time the earning rule is updated. To prevent conflicting changes, the current revision must be passed when updating the earning rule.
You can only call this method when authenticated as a Wix app or Wix user identity.
Loyalty earning rule ID.
Earning rule to update.
The updated earning rule.
curl -X PUT \
'https://www.wixapis.com/loyalty-earning-rules/v1/earning-rules/eeb9ff42-b24f-4a68-8491-21507508f3f5' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"earningRule": {
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"status": "ACTIVE",
"conversionRate": {
"configs": [
{
"points": 20,
"moneyAmount": 1
}
]
},
"revision": 1
}
}'
{
"earningRule": {
"id": "eeb9ff42-b24f-4a68-8491-21507508f3f5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "2",
"createdDate": "2024-09-16T12:12:16.833Z",
"updatedDate": "2024-09-16T14:02:59.364Z",
"metadata": {
"canBeDeleted": true
}
}
}
Retrieves a list of earning rules.
Returns both automated and non-automated earning rules.
You can filter the results by triggerAppId
or triggerActivityType
.
App ID that triggers the point assignment. For example, 9a5d83fd-8570-482e-81ab-cfa88942ee60
.
Type of activity that triggers the point assignment. For example, restaurants-order-is-pending
.
Retrieved earning rules.
curl -X GET \
'https://www.wixapis.com/loyalty-earning-rules/v1/earning-rules/rules' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{
"earningRules": [
{
"id": "eeb9ff42-b24f-4a68-8491-21507508f3f5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:12:16.833Z",
"updatedDate": "2024-09-16T12:12:16.833Z",
"metadata": {
"canBeDeleted": true
}
}
]
}
Triggered when an earning rule is 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.loyalty_earning_rule
.
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.loyalty_earning_rule_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
}
}
}
{
"id": "79e98s2a-d8j4-4a3b-a62f-7393757bab84",
"entityFqdn": "wix.loyalty.v1.loyalty_earning_rule",
"slug": "created",
"entityId": "5bf5cb44-87rt-4933-1234-1d8423636a74",
"createdEvent": {
"entity": {
"id": "b690f925-8527-4d5e-b358-4b0adcb275b5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:06:39.294Z",
"updatedDate": "2024-09-16T12:06:39.294Z",
"metadata": {
"canBeDeleted": true
}
}
},
"eventTime": "2023-09-11T14:58:22.481838Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}
Triggered when an earning rule 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.loyalty_earning_rule
.
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.loyalty_earning_rule_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
}
}
}
{
"id": "79e98s2a-d8j4-4a3b-a62f-7393757bab84",
"entityFqdn": "wix.loyalty.v1.loyalty_earning_rule",
"slug": "updated",
"entityId": "5bf5cb44-87rt-4933-1234-1d8423636a74",
"updatedEvent": {
"currentEntity": {
"id": "b690f925-8527-4d5e-b358-4b0adcb275b5",
"sourceAppId": "553c79f3-5625-4f38-b14b-ef7c0d1e87df",
"triggerAppId": "1380b703-ce81-ff05-f115-39571d94dfcd",
"triggerActivityType": "stores/OrderPaid",
"title": "Purchase a product",
"conversionRate": {
"moneyAmount": 1,
"points": 20,
"configs": [
{
"moneyAmount": 1,
"points": 20
}
]
},
"status": "ACTIVE",
"revision": "1",
"createdDate": "2024-09-16T12:06:39.294Z",
"updatedDate": "2024-09-16T12:06:39.294Z",
"metadata": {
"canBeDeleted": true
}
}
},
"eventTime": "2023-09-11T14:58:22.481838Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}
Triggered when an earning rule 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.loyalty_earning_rule
.
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.loyalty_earning_rule_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
}
}
}
{
"id": "79e98s2a-d8j4-4a3b-a62f-7393757bab84",
"entityFqdn": "wix.loyalty.v1.loyalty_earning_rule",
"slug": "deleted",
"entityId": "5bf5cb44-87rt-4933-1234-1d8423636a74",
"deletedEvent": {},
"eventTime": "2023-09-11T14:58:22.481838Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}