Introduction

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.

Types of referral rewards

The Referral Rewards API supports the following types of rewards:

  • Coupon: A discount or promotional offer that can be applied to a purchase.
  • Loyalty Points: Points awarded to a customer's loyalty account.

Before you begin

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

  • The Referral Program 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.
  • You can only have 1 referral program per site.

Terminology

  • Referral program: A feature that allows your site members to refer friends to your business by sharing referral URLs. You have the option to reward both the customer doing the referring and the friend being referred.
  • 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: An incentive given to both the referring customer and the referred friend for participating in the program.
  • Successful referral action: An action taken by the referred friend that triggers a reward for the referring customer. For example, placing an order, booking a session.
  • Referral URL: A unique link generated for each site member that can be shared with potential new customers The member copies and shares this link with potential customers. When clicked, it brings the referred friend to the site, where they can sign up and redeem their reward.
Did this help?

Program Object


Properties
namestringminLength 2maxLength 50

Referral program name.


statusstringRead-only

revisionintegerformat int64

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.


createdDatestringRead-onlyformat date-time

Date and time the program was created.


updatedDatestringRead-onlyformat date-time

Date and time the program was last updated.


referredFriendRewardReferredFriendReward

Reward configuration for the referred friend. Specifies the reward given to a new customer who was referred to the business.


referringCustomerRewardReferringCustomerReward

Reward configuration for the referring customer. Specifies the reward given to an existing customer who referred a new customer to the business.


successfulReferralActionsArray <string>maxItems 100

List of actions that complete a referral. For an action to be considered successful, the referred friend must place and pay for an item.


emailsEmails

Configures email notifications for the referral program.


premiumFeaturesPremiumFeaturesRead-only

Indicates which premium features are available for the current account.

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

GET

Get Referral Program


Retrieves the referral program.

Endpoint
GET
https://www.wixapis.com/_api/referral-programs/v1/program

Request
This endpoint does not take any parameters.
Response Object
referralProgramReferralProgram

Retrieved referral program.

Get Referral Program
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-programs/v1/program' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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 } } }
Did this help?

PATCH

Update Referral Program


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.

Endpoint
PATCH
https://www.wixapis.com/_api/referral-programs/v1/program

Body Params
referralProgramReferralProgramRequired

Referral program to update. Include the latest revision for a successful update.

Response Object
referralProgramReferralProgram

Updated referral program.

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

PATCH

Activate Referral Program


Activates the referral program, changing its status to ACTIVE.

Endpoint
PATCH
https://www.wixapis.com/_api/referral-programs/v1/program/activate

Request
This endpoint does not take any parameters.
Response Object
referralProgramReferralProgram

Activated referral program.

Activate Referral Program
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/_api/referral-programs/v1/program/activate' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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 } } }
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Pause Referral Program


Pauses the referral program, changing its status to PAUSED.

Endpoint
PATCH
https://www.wixapis.com/_api/referral-programs/v1/program/pause

Request
This endpoint does not take any parameters.
Response Object
referralProgramReferralProgram

Paused referral program.

Pause Referral Program
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/_api/referral-programs/v1/program/pause' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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 } } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get AI Social Media Posts Suggestions


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.

Endpoint
GET
https://www.wixapis.com/_api/referral-programs/v1/program/ai-social-media-posts-suggestions

Query Params
topicstring

Topic to generate social media post suggestions for. For example, fitness, education, technology.

Response Object
suggestionsArray <AISocialMediaPostSuggestion>maxItems 3

Generated social media post suggestions.


referFriendsPageUrlstringmaxLength 2083

Referral URL to refer friends.

Get AI Social Media Posts Suggestions
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-programs/v1/program/ai-social-media-posts-suggestions?topic=first+time+announcement' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "suggestions": [ { "postContent": "Refer a friend to earn points!", "hashtags": ["refer-a-friend", "fitness", "sports"] } ], "referFriendsPageUrl": "https://metasite.wixstudio.io/name/refer-friends" }
Did this help?

POST

Generate AI Social Media Posts Suggestions


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.

Endpoint
POST
https://www.wixapis.com/_api/referral-programs/v1/program/ai-social-media-posts-suggestions

Body Params
topicstringmaxLength 512

Topic to generate social media post suggestions for. For example, fitness, education, technology.

Response Object
suggestionsArray <AISocialMediaPostSuggestion>maxItems 3

Generated social media post suggestions.


referFriendsPageUrlstringmaxLength 2083

Referral URL to refer friends.

Generate AI Social Media Posts Suggestions
Request
cURL
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" }'
Response
JSON
{ "suggestions": [ { "postContent": "Refer a friend to earn points!", "hashtags": ["refer-a-friend", "fitness", "sports"] } ], "referFriendsPageUrl": "https://metasite.wixstudio.io/name/refer-friends" }
Did this help?

GET

Get Referral Program Premium Features


Retrieves information about the enabled premium features for the referral program.

Endpoint
GET
https://www.wixapis.com/_api/referral-programs/v1/program/premium-features

Request
This endpoint does not take any parameters.
Response Object
referralProgramboolean

Whether the site has the referral program feature enabled.

Get Referral Program Premium Features
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-programs/v1/program/premium-features' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "referralProgram": true }
Did this help?

Program Updated


Triggered when a referral program is updated.

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.referral.v1.program.


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