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.
It's important to note the following points before starting to code:
The following table shows field support for filters and sorting for the Referral Event object:
Field | Query Filter Operators | Sortable |
---|---|---|
eventType | $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 Referral Event endpoint Query Referring Customer Totals endpoint Query Referred Friend Actions endpoint
Referral event ID.
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.
Date and time the referral event was created.
Date and time the referral event was last updated.
Event triggered when a referred friend signs up.
Event triggered when a referral is successful. For example, customer places and pays for an order.
Event triggered when an action is performed. For example, placing an order.
Event triggered when a reward is given.
{
"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"
}
}
}
Retrieves a referral event by ID.
ID of the referral event to retrieve.
Retrieved referral event.
curl -X GET \
'https://www.wixapis.com/_api/referral-tracker/v1/referral-events/017fad99-aa0f-47a9-8d4f-177fc6a07da3' \
-H 'Authorization: <AUTH>'
{
"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"
}
}
}
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.
Query to filter referral events
List of referral events.
Metadata for the paginated results.
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"
}
}
}
}'
{
"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
}
}
Retrieves referral statistics.
Total number of sign-ups completed by referred friends.
Total number of actions completed by referred friends.
Total amount of purchases made by referred friends.
curl -X GET \
'https://www.wixapis.com/_api/referral-tracker/v1/referral-statistics' \
-H 'Authorization: <AUTH>'
{
"totalSignUpsCompleted": 16,
"totalActionsCompleted": 5,
"totalAmountGenerated": "815.00"
}
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.referral_event
.
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.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
}
}
}
{
"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"
}
}
}
}