The Referral Program API allows you to create and manage a referral program for Wix sites. With this API, you can incentivize your existing customers to bring in new ones, helping you grow your business through word-of-mouth marketing.
With the Referral Program 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 program on your Wix site.
The Referral Rewards API supports the following types of rewards:
It's important to note the following points before starting to code:
Referral program name.
Revision number, which increments by 1 each time the program is updated.
To prevent conflicting changes, the current revision
must be passed when updating the program.
Date and time the program was created.
Date and time the program was last updated.
Reward configuration for the referred friend. Specifies the reward given to a new customer who was referred to the business.
Reward configuration for the referring customer. Specifies the reward given to an existing customer who referred a new customer to the business.
List of actions that complete a referral. For an action to be considered successful, the referred friend must place and pay for an item.
Configures email notifications for the referral program.
Indicates which premium features are available for the current account.
{
"referralProgram": {
"name": "Share the love!",
"status": "ACTIVE",
"revision": "3",
"createdDate": "2024-01-01T10:49:25.803Z",
"updatedDate": "2024-02-08T05:02:38.276Z",
"referredFriendReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"referringCustomerReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"successfulReferralActions": ["STORE_ORDER_PLACED"],
"emails": {
"encourageToReferFriends": ["STORES"],
"notifyCustomersAboutReward": true
},
"premiumFeatures": {
"referralProgram": true
}
}
}
Retrieves the referral program.
Retrieved referral program.
curl -X GET \
'https://www.wixapis.com/_api/referral-programs/v1/program' \
-H 'Authorization: <AUTH>'
{
"referralProgram": {
"name": "Share the love!",
"status": "ACTIVE",
"revision": "3",
"createdDate": "2024-01-01T10:49:25.803Z",
"updatedDate": "2024-01-02T10:49:25.803Z",
"referredFriendReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"referringCustomerReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"successfulReferralActions": ["STORE_ORDER_PLACED"],
"emails": {
"encourageToReferFriends": ["STORES"],
"notifyCustomersAboutReward": true
},
"premiumFeatures": {
"referralProgram": true
}
}
}
Updates a referral program. Supports partial updates.
Revision number, which increments by 1 each time the referral program is updated. To prevent conflicting changes, the current revision must be passed when updating the referral program.
Referral program to update. Include the latest revision
for a successful update.
Updated referral program.
curl -X PATCH \
'https://www.wixapis.com/_api/referral-programs/v1/program' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
referralProgram": {
"name": "Get a 35% discount for each friend your refer",
"revision": "3"
}
}'
{
"referralProgram": {
"name": "Get a 35% discount for each friend your refer",
"status": "ACTIVE",
"revision": "4",
"createdDate": "2024-01-01T10:49:25.803Z",
"updatedDate": "2024-01-02T10:49:25.803Z",
"referredFriendReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"referringCustomerReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"successfulReferralActions": ["STORE_ORDER_PLACED"],
"isPremium": true,
"emails": {
"encourageToReferFriends": ["STORES"],
"notifyCustomersAboutReward": true
},
"premiumFeatures": {
"referralProgram": true
}
}
}
Activates the referral program, changing its status to ACTIVE
.
Activated referral program.
curl -X PATCH \
'https://www.wixapis.com/_api/referral-programs/v1/program/activate' \
-H 'Authorization: <AUTH>'
{
"referralProgram": {
"name": "Share & Earn",
"status": "ACTIVE",
"revision": "3",
"createdDate": "2024-01-01T10:49:25.803Z",
"updatedDate": "2024-01-02T10:49:25.803Z",
"referredFriendReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"referringCustomerReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"successfulReferralActions": ["STORE_ORDER_PLACED"],
"emails": {
"encourageToReferFriends": ["STORES"],
"notifyCustomersAboutReward": true
},
"premiumFeatures": {
"referralProgram": true
}
}
}
Pauses the referral program, changing its status to PAUSED
.
Paused referral program.
curl -X PATCH \
'https://www.wixapis.com/_api/referral-programs/v1/program/pause' \
-H 'Authorization: <AUTH>'
{
"referralProgram": {
"name": "Refer Your Friends",
"status": "PAUSED",
"revision": "3",
"createdDate": "2024-01-01T10:49:25.803Z",
"updatedDate": "2024-01-02T10:49:25.803Z",
"referredFriendReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"referringCustomerReward": {
"type": "LOYALTY_POINTS",
"loyaltyPointsOptions": {
"amount": 1
}
},
"successfulReferralActions": ["STORE_ORDER_PLACED"],
"emails": {
"encourageToReferFriends": ["STORES"],
"notifyCustomersAboutReward": true
},
"premiumFeatures": {
"referralProgram": true
}
}
}
Retrieves pre-generated AI social media post suggestions for promoting the referral program.
This method returns a list of AI-generated social media post suggestions that site owners or members can use to promote the referral program. You can display these suggestions in your app's UI, allowing users to easily copy and share them on their preferred social media platforms.
Note: This method retrieves existing suggestions. To generate new ones, use the Generate AI Social Media Posts Suggestions method.
Topic to generate social media post suggestions for. For example, fitness, education, technology.
Generated social media post suggestions.
Referral URL to refer friends.
curl -X GET \
'https://www.wixapis.com/_api/referral-programs/v1/program/ai-social-media-posts-suggestions?topic=first+time+announcement' \
-H 'Authorization: <AUTH>'
{
"suggestions": [
{
"postContent": "Refer a friend to earn points!",
"hashtags": ["refer-a-friend", "fitness", "sports"]
}
],
"referFriendsPageUrl": "https://metasite.wixstudio.io/name/refer-friends"
}
Creates new AI-generated social media post suggestions for promoting the referral program.
This method generates new AI-powered social media post suggestions for promoting the referral program. Use it to refresh content or create alternatives to existing suggestions.
Note: This method generates new suggestions each time it's called. To retrieve existing suggestions without generating new ones, use the Get AI Social Media Posts Suggestions method.
Topic to generate social media post suggestions for. For example, fitness, education, technology.
Generated social media post suggestions.
Referral URL to refer friends.
curl -X POST \
'https://www.wixapis.com/_api/referral-programs/v1/program/ai-social-media-posts-suggestions' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"topic": "fitness"
}'
{
"suggestions": [
{
"postContent": "Refer a friend to earn points!",
"hashtags": ["refer-a-friend", "fitness", "sports"]
}
],
"referFriendsPageUrl": "https://metasite.wixstudio.io/name/refer-friends"
}
Retrieves information about the enabled premium features for the referral program.
Whether the site has the referral program feature enabled.
curl -X GET \
'https://www.wixapis.com/_api/referral-programs/v1/program/premium-features' \
-H 'Authorization: <AUTH>'
{
"referralProgram": true
}
Triggered when a referral program 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.referral.v1.program
.
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.referral.v1.program_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
}
}
}