The Referred Friend API allows you to manage referred friends in your referral program on your Wix site.
With the Referred Friend API, you can:
It's important to note the following points before starting to code:
SIGN_UP_COMPLETED
, ACTIONS_COMPLETED
).The following table shows field support for filters and sorting for the Referred Friend object:
Field | Query Filter Operators | Sortable |
---|---|---|
referringCustomerId | $eq , $ne , $hasSome , $startsWith , $in , $nin , $exists | Sortable |
status | $eq , $ne , $hasSome , $startsWith , $in , $nin , $exists | Sortable |
createdDate | $eq , $ne , $hasSome , $in , $nin , $exists , $lt , $lte , $gt , $gte | Sortable |
updatedDate | $eq , $ne , $hasSome , $in , $nin , $exists , $lt , $lte , $gt , $gte | Sortable |
Related content: API Query Language, Query Referred Friend endpoint
ID of the referred friend.
Contact ID of the referred friend.
ID of the customer who referred this friend.
Status of the referred friend.
Revision number, which increments by 1 each time the referred friend is updated. To prevent conflicting changes, the current revision must be passed when updating the referred friend.
Date and time the referred friend was created.
Date and time the referred friend was last updated.
{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
Creates a new referred friend or returns an existing entity if it already exists.
This method must be called with a member identity.
A referral code must be provided either in the request or via scope.
The member must be eligible to become a referred friend.
Referral code for the referred friend.
Created referred friend.
curl -X POST \
'https://www.wixapis.com/referral_friends/v1/referred-friends' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"referralCode": "9zb9JvjwrvQF"
}'
{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "SIGN_UP_COMPLETED",
"revision": "1",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
Retrieves a referred friend by ID.
ID of the referred friend to retrieve.
Retrieved referred friend.
curl -X GET \
'https://www.wixapis.com/referral_friends/v1/referred-friends/3857d039-b129-4393-b983-947078b6a007' \
-H 'Authorization: <AUTH>'
{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
Deletes a referred friend.
ID of the referred friend to delete.
Revision number, which increments by 1 each time the referred friend is updated. To prevent conflicting changes, the current revision must be passed when deleting the referred friend.
curl -X DELETE \
'https://www.wixapis.com/referral_friends/v1/referred-friends/3857d039-b129-4393-b983-947078b6a007' \
-H 'Authorization: <AUTH>'
{}
Retrieves a referred friend by contact ID.
You can use me
instead of a specific contact ID to get the referred friend for the current identity's contact.
Contact ID or "me" to get the current identity's contact.
Retrieved referred friend.
curl -X GET \
'https://www.wixapis.com/referral_friends/v1/referred-friends/contact/me?contactId=me' \
-H 'Authorization: <AUTH>'
{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
Updates a referred friend. Supports partial updates.
You must pass the latest revision
for a successful update.
ID of the referred friend.
Referred friend to be updated. May be partial.
Updated referred friend.
curl -X PATCH \
'https://www.wixapis.com/referral_friends/v1/referred-friends/3857d039-b129-4393-b983-947078b6a007' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"status": "ACTIONS_COMPLETED",
"revision": "2"
}
}'
{
"referredFriend": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "SIGN_UP_COMPLETED",
"revision": "3",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
Retrieves a list of referred friends, given the provided paging, filtering, and sorting.
This endpoint supports WQL (Wix Query Language).
To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
Query options.
Retrieved referred friends.
Cursor paging metadata.
curl -X POST \
'https://www.wixapis.com/referral_friends/v1/referred-friends/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"sort": [
{
"order": "DESC",
"fieldName": "revision"
}
],
"filter": {
"status": "ACTIONS_COMPLETED"
}
}
}'
{
"referredFriends": [
{
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
],
"metadata": {
"count": 1,
"cursors": {
"next": null,
"prev": null
},
"hasNext": false,
"total": null
}
}
Triggered when a referred friend 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.referral.v1.referred_friend
.
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.referral.v1.referred_friend_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
}
}
}
{
"id": "9aca3895-8c58-48b7-84a5-35bcd431c125",
"entityFqdn": "wix.loyalty.referral.v1.referred_friend",
"slug": "created",
"entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0",
"eventTime": "2024-08-12T08:12:17.813Z",
"createdEvent": {
"entity": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
}
Triggered when a referred friend 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.referred_friend
.
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.referred_friend_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
}
}
}
{
"id": "9aca3895-8c58-48b7-84a5-35bcd431c125",
"entityFqdn": "wix.loyalty.referral.v1.referred_friend",
"slug": "updated",
"entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0",
"eventTime": "2024-08-12T08:12:17.813Z",
"updatedEvent": {
"currentEntity": {
"id": "3857d039-b129-4393-b983-947078b6a007",
"contactId": "661f5bb3-0723-4aa4-87d7-a21ebd1d0fa3",
"referringCustomerId": "07a3306c-b311-466e-92dd-c635c4145d1c",
"status": "ACTIONS_COMPLETED",
"revision": "2",
"createdDate": "2024-08-12T08:12:17.813Z",
"updatedDate": "2024-08-12T08:13:27.708Z"
}
}
}
Triggered when a referred friend 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.referral.v1.referred_friend
.
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.referral.v1.referred_friend_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
}
}
}
{
"id": "9aca3895-8c58-48b7-84a5-35bcd431c125",
"entityFqdn": "wix.loyalty.referral.v1.referred_friend",
"slug": "deleted",
"entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0",
"deletedEvent": {},
"eventTime": "2024-08-12T08:12:17.813Z",
"triggeredByAnonymizeRequest": true
}