Introduction

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.

Terminology

  • Discount amount: A flexible reward type which allows to redeem points and get discount inside a checkout.
  • Coupon reward: All other types of rewards other than “discount amount.” The details included here dictate what type of coupon will be created when this reward is redeemed.
Did this help?

Reward Object


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.

Properties
idstringRead-onlyformat GUID

Reward ID.


namestringminLength 1maxLength 50

Reward name.


activeboolean

Whether the reward is active. Default: FALSE


typestring

Reward type.


revisionintegerRead-onlyformat uint64

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.


createdDatestringRead-onlyformat date-time

Date and time the reward was created.


updatedDatestringRead-onlyformat date-time

Date and time the reward was last updated.


ONE OF:

discountAmountDiscountAmount

Discount details.


couponRewardCouponReward

Coupon details.

Reward
JSON
{ "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" } }
Did this help?

GET

List Rewards


Retrieves a list of rewards.

The list includes rewards that are currently nonredeemable due to insufficient points held by any customers.

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

Query Params
cursorPaging.limitintegerminimum 0maximum 100format int32

Maximum number of items to return in the results.


cursorPaging.cursorstringmaxLength 16000

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.

Response Object
rewardsArray <Reward>

Retrieved loyalty rewards.


pagingMetadataPagingMetadata

Details on the paged set of results returned.

List rewards
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-rewards/v1/rewards' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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": {} } }
Did this help?

POST

Create Reward


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.

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-rewards/v1/rewards

Body Params
rewardRewardRequired

Reward to create.

Response Object
rewardReward

Created reward.

Create reward
Request
cURL
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 } ] } } } }'
Response
JSON
{ "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" } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Bulk Create Rewards


Creates multiple rewards.

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-rewards/v1/bulk/rewards/create

Body Params
rewardsArray <Reward>RequiredminItems 1maxItems 10

Rewards to create.

Response Object
resultsArray <BulkRewardResult>

Created rewards.


bulkActionMetadataBulkActionMetadata

Total successes and failures of the bulk create rewards action.

Bulk create rewards
Request
cURL
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 } ] } } } ] }'
Response
JSON
{ "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 } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Reward


Retrieves a reward.

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

Path Params
idstringRequired

ID of the reward to retrieve.

Response Object
rewardReward

Retrieved reward.

Get reward
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-rewards/v1/rewards/46d7bbce-6bb4-4174-ae5a-7f44c19f95ce' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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" } }
Did this help?

DELETE

Delete Reward


Deletes a reward.

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-rewards/v1/rewards/{id}

Path Params
idstringRequired

ID of the reward to delete.

Query Params
revisionnumber

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.

Response Object
Returns an empty object.
Delete reward
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/loyalty-rewards/v1/rewards/46d7bbce-6bb4-4174-ae5a-7f44c19f95ce?revision=1' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

POST

Query Rewards


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.

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

Body Params
queryQueryRequired

Query parameters.

Response Object
rewardsArray <Reward>

Retrieved loyalty rewards.


pagingMetadataPagingMetadata

Details on the paged set of results returned.

Query rewards
Request
cURL
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"}} } }'
Response
JSON
{ "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 } }
Did this help?

PUT

Update Reward


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.

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
PUT
https://www.wixapis.com/loyalty-rewards/v1/rewards/{reward.id}

Path Params
reward.idstringRequired

Reward ID.

Body Params
rewardRewardRequired

Reward information to update.

Response Object
rewardReward

Updated reward.

Update reward
Request
cURL
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 } ] } } } }'
Response
JSON
{ "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" } }
Event TriggersThis method triggers the following events:
Did this help?

Reward Created


Triggered when a reward is created.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
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.reward.


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

Reward Updated


Triggered when a reward is updated.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
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.reward.


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

Reward Deleted


Triggered when a reward is deleted.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
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.reward.


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