Introduction

The Referral Rewards API allows you to retrieve information about referral rewards on your Wix site. With this API, you can access data about rewards given to customers who participate in your referral program.

With the Referral Rewards API, you can:

See the Wix Referral Program: Adding and Setting Up Your Referral Program article for more information on setting up and managing referral programs on your Wix site.

Before you begin

It's important to note the following points before starting to code:

  • The Referral Rewards API requires a Business or higher plan for Wix Editor, or a Plus or higher plan for Wix Studio.
  • You must have at least one of these apps installed: Wix Stores, Wix Bookings, Wix Events, Wix Pricing Plans, or the new Wix Restaurants ordering app.

Terminology

  • Referral Reward: An incentive given to either the referring customer or the referred friend for participating in the referral program.
  • Referring Customer: A site member who shares a referral URL with potential new customers.
  • Referred Friend: A person who clicks on a referral URL shared by a referring customer.
  • Reward Type: The type of reward, which can be a coupon or loyalty points.
  • Owner Type: Indicates whether the reward belongs to the referring customer or the referred friend.
Did this help?

Referral Reward: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Referral Reward object:

FieldQuery Filter OperatorsSortable
rewardedReferringCustomerId$eq, $ne, $hasSome, $exists, $startsWith, $in, $ninSortable
rewardedReferredFriendId$eq, $ne, $hasSome, $exists, $startsWith, $in, $ninSortable
rewardType$eq, $ne, $hasSome, $in, $nin, $existsSortable
createdDate$eq, $ne, $lt, $lte, $gt, $gte, $hasSome, $in, $nin, $existsSortable
updatedDate$eq, $ne, $lt, $lte, $gt, $gte, $hasSome, $in, $nin, $existsSortable

Related content: API Query Language, Query Referral Rewards endpoint

Did this help?

Referral Reward Object


Properties
idstringRead-onlyformat GUID

Referral reward ID.


revisionintegerformat int64

Revision number, which increments by 1 each time the referral reward is updated. To prevent conflicting changes, the current revision must be passed when updating the referral reward.


createdDatestringRead-onlyformat date-time

Date and time the referral reward was created.


updatedDatestringRead-onlyformat date-time

Date and time the referral reward was last updated.


rewardTypestring

Type of reward given.


ONE OF:

rewardedReferringCustomerIdstringRead-onlyformat GUID

ID of the referring customer who received the reward.


rewardedReferredFriendIdstringRead-onlyformat GUID

ID of the referred friend who received the reward.


ONE OF:

couponCoupon

Details of a coupon reward. Present when reward_type is COUPON.


loyaltyPointsLoyaltyPoints

Details of a loyalty points reward. Present when reward_type is LOYALTY_POINTS.

ReferralReward
JSON
{ "referralReward": { "id": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "revision": "2", "createdDate": "2024-07-08T11:22:00.728Z", "updatedDate": "2024-07-08T11:27:57.197Z", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866", "coupon": { "id": "43fa238a-b464-4a5b-9079-5682a5a1eab7", "code": "6QW1ASGTZ0Q4", "status": "APPLIED", "couponSpecification": { "name": "Your reward", "discountType": "FIXED_AMOUNT", "limitedToOneItem": true, "appliesToSubscriptions": null, "discountedCycleCount": null, "fixedAmountOptions": { "amount": 10 }, "scope": { "namespace": "stores", "group": null } } } } }
Did this help?

GET

Get Referral Reward


Retrieves a referral reward.

Endpoint
GET
https://www.wixapis.com/_api/referral-rewards/v1/referral-rewards/{id}

Path Params
idstringRequired

Referral reward ID.

Response Object
referralRewardReferralReward

Retrieved referral reward.

Get Referral Reward
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-rewards/v1/referral-rewards/c8c732cf-2ca2-4025-9b1c-3be02f099cdb' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "referralReward": { "id": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "revision": "2", "createdDate": "2024-07-08T11:22:00.728Z", "updatedDate": "2024-07-08T11:27:57.197Z", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866", "coupon": { "id": "43fa238a-b464-4a5b-9079-5682a5a1eab7", "code": "6QW1ASGTZ0Q4", "status": "APPLIED", "couponSpecification": { "name": "Your reward", "discountType": "FIXED_AMOUNT", "limitedToOneItem": true, "appliesToSubscriptions": null, "discountedCycleCount": null, "fixedAmountOptions": { "amount": 10 }, "scope": { "namespace": "stores", "group": null } } } } }
Did this help?

POST

Query Referral Rewards


Retrieves a list of referral rewards, given the provided paging, filtering, and sorting.

To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.

Endpoint
POST
https://www.wixapis.com/_api/referral-rewards/v1/referral-rewards/query

Body Params
queryQueryRequired

Query to filter referral rewards.


contactIdstring

Contact ID to filter rewards by. Use "me" for current identity's rewards.

Response Object
referralRewardsArray <ReferralReward>

Retrieved referral rewards.


metadataMetadata

Metadata for paging.

Query Referral Rewards
Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/referral-rewards/v1/referral-rewards/query' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "query": { "sort": [ { "order": "DESC", "fieldName": "revision" } ], "filter": { "rewardType": "CouponReward" } }, "contactId": "me" }'
Response
JSON
{ "referralRewards": [ { "id": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "revision": "2", "createdDate": "2024-07-08T11:22:00.728Z", "updatedDate": "2024-07-08T11:27:57.197Z", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866", "coupon": { "id": "43fa238a-b464-4a5b-9079-5682a5a1eab7", "code": "6QW1ASGTZ0Q4", "status": "APPLIED", "couponSpecification": { "name": "Your reward", "discountType": "FIXED_AMOUNT", "limitedToOneItem": true, "appliesToSubscriptions": null, "discountedCycleCount": null, "fixedAmountOptions": { "amount": 10 }, "scope": { "namespace": "stores", "group": null } } } } ], "metadata": { "count": 1, "cursors": {}, "hasNext": false } }
Did this help?