Introduction

The Referral Tracker API allows you to monitor and analyze referral events in your Wix site's referral program.

With the Referral Tracker API, you can:

For more information about managing loyalty programs, see the Loyalty API. To learn more about referral programs, see Managing Your Referral Program.

Before you begin

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

  • To use the Referral Tracker API, you need to have the Wix Loyalty Program app installed on your site.
  • The Referral Tracker 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 Event: A record of an action related to your referral program, such as a signup or a successful referral.
  • Referring Customer: A customer who refers friends to your site.
  • Referred Friend: A person who signs up or takes an action on your site after being referred by a customer.
  • Referral Statistics: Overall metrics about your referral program's performance.
  • Referral Reward: A benefit given to either the referring customer or the referred friend for participating in the referral program.
  • Trigger: The specific action that initiates a referral event, such as a signup or a purchase.
  • Reward Type: The type of benefit given for a successful referral, which can be a coupon, loyalty points, or no reward.
Did this help?

Referral Tracker: Supported Filters and Sorting

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

FieldQuery Filter OperatorsSortable
eventType$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 Referral Event endpoint Query Referring Customer Totals endpoint Query Referred Friend Actions endpoint

Did this help?

Referral Event Object


Properties
idstringRead-onlyformat GUID

Referral event ID.


revisionintegerformat int64

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


createdDatestringRead-onlyformat date-time

Date and time the referral event was created.


updatedDatestringRead-onlyformat date-time

Date and time the referral event was last updated.


ONE OF:

referredFriendSignupEventReferredFriendSignupEvent

Event triggered when a referred friend signs up.


successfulReferralEventSuccessfulReferralEvent

Event triggered when a referral is successful. For example, customer places and pays for an order.


actionEventActionEvent

Event triggered when an action is performed. For example, placing an order.


rewardEventRewardEvent

Event triggered when a reward is given.

ReferralEvent
JSON
{ "referralEvent": { "id": "017fad99-aa0f-47a9-8d4f-177fc6a07da3", "revision": "1", "createdDate": "2024-07-08T11:22:00.826Z", "updatedDate": "2024-07-08T11:22:00.826Z", "rewardEvent": { "referralRewardId": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866" } } }
Did this help?

GET

Get Referral Event


Retrieves a referral event by ID.

Endpoint
GET
https://www.wixapis.com/_api/referral-tracker/v1/referral-events/{referralEventId}

Path Params
referralEventIdstringRequired

ID of the referral event to retrieve.

Response Object
referralEventReferralEvent

Retrieved referral event.

Get Referral Event
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-tracker/v1/referral-events/017fad99-aa0f-47a9-8d4f-177fc6a07da3' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "referralEvent": { "id": "017fad99-aa0f-47a9-8d4f-177fc6a07da3", "revision": "1", "createdDate": "2024-07-08T11:22:00.826Z", "updatedDate": "2024-07-08T11:22:00.826Z", "rewardEvent": { "referralRewardId": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866" } } }
Did this help?

POST

Query Referral Event


Retrieves a list of referral events, 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-tracker/v1/referral-events/query

Body Params
queryQueryRequired

Query to filter referral events

Response Object
referralEventsArray <ReferralEvent>

List of referral events.


metadataMetadata

Metadata for the paginated results.

Query Referral Event
Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/referral-tracker/v1/referral-events/query' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "query": { "filter": { "createdDate": { "$gt": "2024-06-08T00:00:00.000Z" } } } }'
Response
JSON
{ "referralEvents": [ { "id": "017fad99-aa0f-47a9-8d4f-177fc6a07da3", "revision": "1", "createdDate": "2024-07-08T11:22:00.826Z", "updatedDate": "2024-07-08T11:22:00.826Z", "rewardEvent": { "referralRewardId": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866" } }, { "id": "0c1d6dbe-7825-4dae-98dd-398ca10f4b9a", "revision": "1", "createdDate": "2024-07-24T10:44:12.915Z", "updatedDate": "2024-07-24T10:44:12.915Z", "referredFriendSignupEvent": { "referredFriendId": "a1b42d76-7b7f-4ed6-b2cd-5937dfd3e9ff" } } ], "metadata": { "count": 2, "cursors": {}, "hasNext": false } }
Did this help?

GET

Get Referral Statistics


Retrieves referral statistics.

Endpoint
GET
https://www.wixapis.com/_api/referral-tracker/v1/referral-statistics

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

Total number of sign-ups completed by referred friends.


totalActionsCompletedinteger

Total number of actions completed by referred friends.


totalAmountGeneratedstring

Total amount of purchases made by referred friends.

Get Referral Statistics
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/referral-tracker/v1/referral-statistics' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "totalSignUpsCompleted": 16, "totalActionsCompleted": 5, "totalAmountGenerated": "815.00" }
Did this help?

Referral Event 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.referral_event.


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

ReferralEventCreated
JSON
{ "id": "9aca3895-8c58-48b7-84a5-35bcd431c125", "entityFqdn": "wix.loyalty.referral.v1.referral_event", "slug": "created", "entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0", "cratedEvent": { "entity": { "id": "017fad99-aa0f-47a9-8d4f-177fc6a07da3", "revision": "1", "createdDate": "2024-07-08T11:22:00.826Z", "updatedDate": "2024-07-08T11:22:00.826Z", "rewardEvent": { "referralRewardId": "c8c732cf-2ca2-4025-9b1c-3be02f099cdb", "rewardType": "COUPON", "rewardedReferringCustomerId": "4fb41de4-da9c-4818-b54f-82c955ecc866" } } } }
Did this help?