The Loyalty Rewards API allows you to manage rewards that customers can redeem with their loyalty points.For example, you can create a reward that is redeemed for a coupon for free shipping or for a coupon with a discount that applies to an entire purchase.
With the Loyalty Rewards API, you can create and update the rewards you offer.
A loyalty reward is an object a customer can redeem with loyalty points. Redeeming a reward then creates a loyalty coupon that the customer can use.
Reward ID.
Reward name.
Whether the reward is active. Default: FALSE
Reward type.
Revision number, which increments by 1 each time the loyalty reward is updated.
To prevent conflicting changes, the current revision
must be passed when updating the loyalty reward.
Date and time the reward was created.
Date and time the reward was last updated.
Discount details.
Coupon details.
{
"reward": {
"id": "00000000-0000-0000-0001-000000000000",
"name": "Flexible reward",
"requiredPoints": 10,
"active": true,
"type": "DISCOUNT_AMOUNT",
"discountAmount": {
"amount": "1",
"configsByTier": [
{
"amount": "1",
"costInPoints": 10
}
]
},
"revision": "3",
"createdDate": "2024-02-09T09:07:32.797Z",
"updatedDate": "2024-03-07T15:47:19.402Z"
}
}
Retrieves a list of rewards.
The list includes rewards that are currently nonredeemable due to insufficient points held by any customers.
Maximum number of items to return in the results.
Pointer to the next or previous page in the list of results.
Pass the relevant cursor token from the pagingMetadata
object in the previous call's response.
Not relevant for the first request.
Retrieved loyalty rewards.
Details on the paged set of results returned.
curl -X GET \
'https://www.wixapis.com/loyalty-rewards/v1/rewards' \
-H 'Authorization: <AUTH>'
{
"rewards": [
{
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
}
]
}
},
"revision": "1",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
}
],
"pagingMetadata": {
"count": 1,
"total": 1,
"cursors": {}
}
}
Creates a reward that can be redeemed with loyalty points.
When a customer redeems a reward, a loyalty coupon is created
based on the specifications detailed in either the discountAmount
or couponReward
fields. This coupon can
then be used by the customer to receive the discount. Note that while the Rewards API uses coupon scopes and specifications,
no coupon is actually created until a reward is redeemed with points.
See the Coupons API for more information about coupons. The type
of reward
cannot be updated.
A reward's active
status defaults to false
. To make the reward available to customers,
either set the active
field to true
during creation or call Update Reward
to change the status.
To customize a reward for each loyalty tier, use the configsByTier
parameter.
This allows you to specify the amount of the earned discount, the cost in loyalty points
to redeem the reward, and the tier to which this configuration applies. Each tier requires its own
configsByTier
configuration. To create a reward that is available to loyalty accounts in the base tier,
leave the tierId
field empty. See the Tiers API for more information on tiers.
You can only call this method when authenticated as a Wix app or Wix user identity.
Reward to create.
Created reward.
curl -X POST \
'https://www.wixapis.com/loyalty-rewards/v1/rewards' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
--data-raw '{
"reward": {
"active": true,
"name": "Free shipping",
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"tierId": null,
"costInPoints": 20
}
]
}
}
}
}'
{
"reward": {
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
}
]
}
},
"revision": "1",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
}
}
Creates multiple rewards.
You can only call this method when authenticated as a Wix app or Wix user identity.
Rewards to create.
Created rewards.
Total successes and failures of the bulk create rewards action.
curl -X POST \
'https://www.wixapis.com/loyalty-rewards/bulk/rewards/create' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
--data-raw '{
"rewards": [
{
"active": true,
"name": "Free shipping",
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"tierId": null,
"costInPoints": 20
}
]
}
}
}
]
}'
{
"results": [
{
"item": {
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
}
]
}
},
"revision": "1",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
},
"itemMetadata": {
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"originalIndex": 0,
"success": true,
"error": null
}
}
],
"bulkActionMetadata": {
"totalSuccesses": 1,
"totalFailures": 0,
"undetailedFailures": 0
}
}
Retrieves a reward.
ID of the reward to retrieve.
Retrieved reward.
curl -X GET \
'https://www.wixapis.com/loyalty-rewards/v1/rewards/46d7bbce-6bb4-4174-ae5a-7f44c19f95ce' \
-H 'Authorization: <AUTH>'
{
"reward": {
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
}
]
}
},
"revision": "1",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
}
}
Deletes a reward.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the reward to delete.
Revision number, which increments by 1 each time the reward is updated.
To prevent conflicting changes, the current revision
must be passed when deleting the reward.
curl -X DELETE \
'https://www.wixapis.com/loyalty-rewards/v1/rewards/46d7bbce-6bb4-4174-ae5a-7f44c19f95ce?revision=1' \
-H 'Authorization: <AUTH>'
{}
Retrieves a list of rewards, given the provided paging, filtering, and sorting.
Query Rewards runs with these defaults, which you can override: cursorPaging.limit
is 50
.
To learn about working with Query endpoints, see API Query Language,Sorting and Paging,and Field Projection.
Query parameters.
Retrieved loyalty rewards.
Details on the paged set of results returned.
curl -X POST \
'https://www.wixapis.com/loyalty-rewards/v1/rewards/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
--data-raw '{
"query": {
"filter": {"name": {"$startsWith": "Free"}}
}
}'
{
"rewards": [
{
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
}
]
}
},
"revision": "1",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
}
],
"pagingMetadata": {
"count": 1,
"cursors": {},
"hasNext": false
}
}
Updates a loyalty reward.
Use this endpoint to update details of a reward, such as the name, whether or not a reward is active, or the amount of points it costs to redeem. Also use this endpoint to add new tiers that are eligible to redeem a reward.
You may not change the type
of a reward. That is set upon creation and cannot be updated.
You can only call this method when authenticated as a Wix app or Wix user identity.
Reward ID.
Reward information to update.
Updated reward.
curl -X PUT \
'https://www.wixapis.com/loyalty-rewards/v1/rewards/46d7bbce-6bb4-4174-ae5a-7f44c19f95ce' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
--data-raw '{
"reward": {
"active": true,
"name": "Free shipping",
"type": "COUPON_REWARD",
"revision": "1",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"tierId": null,
"costInPoints": 20
},
{
"tierId": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb",
"costInPoints": 15
}
]
}
}
}
}'
{
"reward": {
"id": "46d7bbce-6bb4-4174-ae5a-7f44c19f95ce",
"name": "Free shipping",
"requiredPoints": 20,
"active": true,
"type": "COUPON_REWARD",
"couponReward": {
"freeShipping": {
"configsByTier": [
{
"costInPoints": 20
},
{
"tierId": "acddc0e0-5e27-4a1b-a52d-b3785ac258cb",
"costInPoints": 15
}
]
}
},
"revision": "2",
"createdDate": "2024-04-18T10:35:41.071Z",
"updatedDate": "2024-04-18T10:35:41.071Z"
}
}
Triggered when a reward 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.reward
.
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.reward_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 reward 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.reward
.
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.reward_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 reward 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.reward
.
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.reward_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
}
}
}