Introduction

The Referring Customers API allows you to manage referring customers on your Wix site.

With the Referring Customers API, you can:

Before you begin

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

  • The Referring Customers 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

  • Referring Customer: An existing customer who refers others to your site or business.
  • Referred Friend: A person who clicks on a referral URL shared by a referring customer.
  • 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.
  • Referral Reward: An incentive given to a referring customer when their referral results in a desired action such as making a purchase.
Did this help?

Referring Customers: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Referring Customer object:

FieldQuery Filter OperatorsSortable
contactId$eq, $ne, $hasSome, $startsWith, $in, $nin, $existsSortable
referralCode$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 Referring Customers endpoint

Did this help?

Referring Customer Object


Properties
idstringRead-onlyformat GUID

ID of the referring customer.


contactIdstringRead-onlyformat GUID

Contact ID associated with the referring customer.


referralCodestringRead-onlyminLength 12maxLength 12

Unique code for the referral. For example, GxpxwAoMqxH8.


revisionintegerformat int64

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.


createdDatestringRead-onlyformat date-time

Date and time the referring customer was created.


updatedDatestringRead-onlyformat date-time

Date and time the referring customer was last updated.

ReferringCustomer
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" } }
Did this help?

POST

Generate Referring Customer For Contact


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.

Endpoint
POST
https://www.wixapis.com/referral-customers/v1/referring-customers

Body Params
contactIdstringRequiredminLength 2

Contact ID or "me" to generate the current identity's referring customer.

Response Object
referringCustomerReferringCustomer

Created referring customer.

Generate Referring Customer for Contact
Request
cURL
curl -X POST \ 'https://www.wixapis.com/referral-customers/v1/referring-customers' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "contactId": "me" }'
Response
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" }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Referring Customer


Retrieves a referring customer by ID.

Endpoint
GET
https://www.wixapis.com/referral-customers/v1/referring-customers/{referringCustomerId}

Path Params
referringCustomerIdstringRequired

ID of the referring customer to retrieve.

Response Object
referringCustomerReferringCustomer

Retrieved referring customer.

Get Referring Customer
Request
cURL
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' \
Response
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" }
Did this help?

DELETE

Delete Referring Customer


Deletes a referring customer by ID.

You must provide the latest revision to prevent conflicting changes.

Endpoint
DELETE
https://www.wixapis.com/referral-customers/v1/referring-customers/{referringCustomerId}

Path Params
referringCustomerIdstringRequired

ID of the referring customer to delete.

Query Params
revisioninteger

Revision number of the referring customer.

Response Object
Returns an empty object.
Delete Referring Customer
Request
cURL
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' \
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Referring Customer By Referral Code


Retrieves a referring customer by referral code.

Endpoint
GET
https://www.wixapis.com/referral-customers/v1/referring-customers/code/{referralCode}

Path Params
referralCodestringRequired

Referral code of the referring customer to retrieve.

Response Object
referringCustomerReferringCustomer

Retrieved referring customer.

Get Referring Customer by Referral Code
Request
cURL
curl -X GET \ 'https://www.wixapis.com/referral-customers/v1/referring-customers/code/9zb9JvjwrvQF' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
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" }
Did this help?

POST

Query Referring Customers


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.

Endpoint
POST
https://www.wixapis.com/referral-customers/v1/referring-customers/query

Body Params
queryQueryRequired

Query options.

Response Object
referringCustomersArray <ReferringCustomer>

List of retrieved referring customers.


metadataMetadata

Paging metadata.

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

Referring Customer Created


Triggered when a referring customer 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.referring_customer.


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

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

Referring Customer Deleted


Triggered when a referring customer 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.referring_customer.


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

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