Introduction

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:

Before you begin

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

  • The Referred Friend 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

  • Referred Friend: A person who clicks on a referral URL shared by a referring customer.
  • Referring Customer: A site member who shares a referral URL with potential new customers.
  • Referral Code: A unique code assigned to a referring customer.
  • 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.
  • Status: The current state of a referred friend in the referral program (for example, SIGN_UP_COMPLETED, ACTIONS_COMPLETED).
Did this help?

Referred Friend: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Referred Friend object:

FieldQuery Filter OperatorsSortable
referringCustomerId$eq, $ne, $hasSome, $startsWith, $in, $nin, $existsSortable
status$eq, $ne, $hasSome, $startsWith, $in, $nin, $existsSortable
createdDate$eq, $ne, $hasSome, $in, $nin, $exists, $lt, $lte, $gt, $gteSortable
updatedDate$eq, $ne, $hasSome, $in, $nin, $exists, $lt, $lte, $gt, $gteSortable

Related content: API Query Language, Query Referred Friend endpoint

Did this help?

Referred Friend Object


Properties
idstringRead-onlyformat GUID

ID of the referred friend.


contactIdstringRead-onlyformat GUID

Contact ID of the referred friend.


referringCustomerIdstringRead-onlyformat GUID

ID of the customer who referred this friend.


statusstring

Status of the referred friend.


revisionintegerRead-onlyformat int64

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.


createdDatestringRead-onlyformat date-time

Date and time the referred friend was created.


updatedDatestringRead-onlyformat date-time

Date and time the referred friend was last updated.

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

POST

Create Referred Friend


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.

Endpoint
POST
https://www.wixapis.com/referral_friends/v1/referred-friends

Body Params
referralCodestringminLength 12maxLength 12

Referral code for the referred friend.

Response Object
referredFriendReferredFriend

Created referred friend.

Create Referred Friend
Request
cURL
curl -X POST \ 'https://www.wixapis.com/referral_friends/v1/referred-friends' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "referralCode": "9zb9JvjwrvQF" }'
Response
JSON
{ "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" } }
Errors
428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

GET

Get Referred Friend


Retrieves a referred friend by ID.

Endpoint
GET
https://www.wixapis.com/referral_friends/v1/referred-friends/{referredFriendId}

Path Params
referredFriendIdstringRequired

ID of the referred friend to retrieve.

Response Object
referredFriendReferredFriend

Retrieved referred friend.

Get Referred Friend
Request
cURL
curl -X GET \ 'https://www.wixapis.com/referral_friends/v1/referred-friends/3857d039-b129-4393-b983-947078b6a007' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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" } }
Did this help?

DELETE

Delete Referred Friend


Deletes a referred friend.

Endpoint
DELETE
https://www.wixapis.com/referral_friends/v1/referred-friends/{referredFriendId}

Path Params
referredFriendIdstringRequired

ID of the referred friend to delete.

Query Params
revisioninteger

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.

Response Object
Returns an empty object.
Delete Referred Friend
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/referral_friends/v1/referred-friends/3857d039-b129-4393-b983-947078b6a007' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Referred Friend By Contact Id


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.

Endpoint
GET
https://www.wixapis.com/referral_friends/v1/referred-friends/contact/{contactId}

Path Params
contactIdstringRequired

Contact ID or "me" to get the current identity's contact.

Response Object
referredFriendReferredFriend

Retrieved referred friend.

Get Referred Friend by Contact Id
Request
cURL
curl -X GET \ 'https://www.wixapis.com/referral_friends/v1/referred-friends/contact/me?contactId=me' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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" } }
Did this help?

PATCH

Update Referred Friend


Updates a referred friend. Supports partial updates.

You must pass the latest revision for a successful update.

Endpoint
PATCH
https://www.wixapis.com/referral_friends/v1/referred-friends/{referredFriend.id}

Path Params
referredFriend.idstringRequired

ID of the referred friend.

Body Params
referredFriendReferredFriendRequired

Referred friend to be updated. May be partial.

Response Object
referredFriendReferredFriend

Updated referred friend.

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

POST

Query Referred Friend


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.

Endpoint
POST
https://www.wixapis.com/referral_friends/v1/referred-friends/query

Body Params
queryQueryRequired

Query options.

Response Object
referredFriendsArray <ReferredFriend>

Retrieved referred friends.


metadataMetadata

Cursor paging metadata.

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

Referred Friend Created


Triggered when a referred friend is created.

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.referred_friend.


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.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 } } }

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

Referred Friend Updated


Triggered when a referred friend 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.referred_friend.


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.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 } } }

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

Referred Friend Deleted


Triggered when a referred friend is deleted.

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.referred_friend.


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.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 } } }

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