The Referring Customers API allows you to manage referring customers on your Wix site.
With the Referring Customers API, you can:
It's important to note the following points before starting to code:
The following table shows field support for filters and sorting for the Referring Customer object:
Field | Query Filter Operators | Sortable |
---|---|---|
contactId | $eq , $ne , $hasSome , $startsWith , $in , $nin , $exists | Sortable |
referralCode | $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 Referring Customers endpoint
ID of the referring customer.
Contact ID associated with the referring customer.
Unique code for the referral. For example, GxpxwAoMqxH8
.
Revision number, which increments by 1 each time the referring customer is updated. To prevent conflicting changes, the current revision must be passed when updating the referring customer.
Date and time the referring customer was created.
Date and time the referring customer was last updated.
{
"referringCustomer": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
}
Creates a new referring customer or returns an existing one for the provided contact ID.
You can use me
instead of a specific contact ID to generate a referring customer for the current identity's contact.
See the About Identities article to learn more about identies.
Contact ID or "me"
to generate the current identity's referring customer.
Created referring customer.
curl -X POST \
'https://www.wixapis.com/referral-customers/v1/referring-customers' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"contactId": "me"
}'
{
"referringCustomer": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
Retrieves a referring customer by ID.
ID of the referring customer to retrieve.
Retrieved referring customer.
curl -X GET \
'https://www.wixapis.com/referral-customers/v1/referring-customers/46d7bbce-6bb4-4174-ae5a-7f44c19f95' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
{
"referringCustomer": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
Deletes a referring customer by ID.
You must provide the latest revision
to prevent conflicting changes.
ID of the referring customer to delete.
Revision number of the referring customer.
curl -X DELETE \
'https://www.wixapis.com/referral-customers/v1/referring-customers/46d7bbce-6bb4-4174-ae5a-7f44c19f95?revision=1' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
{}
Retrieves a referring customer by referral code.
Referral code of the referring customer to retrieve.
Retrieved referring customer.
curl -X GET \
'https://www.wixapis.com/referral-customers/v1/referring-customers/code/9zb9JvjwrvQF' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
{
"referringCustomer": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
Retrieves a list of referred friends, 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 options.
List of retrieved referring customers.
Paging metadata.
curl -X POST \
'https://www.wixapis.com/referral-customers/v1/referring-customers/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a"
}
}
}'
{
"referringCustomers": [
{
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
],
"metadata": {
"count": 1,
"cursors": {},
"hasNext": false
}
}
Triggered when a referring customer 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.referring_customer
.
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.referring_customer_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.referring_customer",
"slug": "created",
"entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0",
"createdEvent": {
"entity": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"contactId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"referralCode": "9zb9JvjwrvQF",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z"
}
}
}
Triggered when a referring customer 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.referring_customer
.
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.referring_customer_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": "85deb868-5896-4a44-8f0a-3544eb432216",
"entityFqdn": "wix.loyalty.referral.v1.referring_customer",
"slug": "deleted",
"entityId": "077766f0-ffa4-4fa1-bdf8-dbb0439c1892",
"deletedEvent": {},
"eventTime": "2023-05-25T10:57:03.945444Z",
"triggeredByAnonymizeRequest": false
}