The Loyalty Imports API allows you to import loyalty data for existing customers from external sources into your Wix site's loyalty program. You can track import progress, handle any errors that may occur during the process, and manage your loyalty data efficiently.
With the Loyalty Imports API, you can:
For more information about managing your site's loyalty program, see the Wix Loyalty Program API.
It's important to note the following points before starting to code:
10MB
.The loyalty import process follows these phases:
When creating your loyalty data file for import, consider the following guidelines:
Your import file must contain at least two required fields:
Prepare your data in a CSV (Comma-Separated Values) format. Here's an example of what your import file might look like:
Name,Email,Points balance,Redeemed points,Last activity
Emma Smith,emma.smith@example.com,400,0,2024-08-23T13:19:12.355Z
Ahmed Hassan,ahmed.hassan@example.com,200,0,2024-08-23T13:18:59.984Z
Mia Anderson,mia.anderson@example.com,200,0,2024-08-22T10:05:19.967Z
The import process uses the email address as the unique identifier for each customer. If an email address in the import file doesn't match an existing customer, that row is skipped and logged as an error.
During the import:
The importResult
property of the Loyalty Import object contains the results of the import:
successCount
: Number of successfully imported customer recordsfailureCount
: Number of customer records that couldn't be importederrorFileExists
: Indicates whether an error file is available for downloadThe parseResult
property provides information about the initial file parsing:
parsedRowCount
: Total number of rows processed from the import fileFor example, if you import a file with 3 customers and 1 fails to import, the response might look like this:
{
"parseResult": {
"parsedRowCount": 3
},
"importResult": {
"errorFileExists": true,
"successCount": 2,
"failureCount": 1
}
}
This indicates:
If errors occur, call Get Error File Download Url
to retrieve detailed error information. The error file will contain specific details about why certain rows failed to import, such as unmatched email addresses or invalid point values.
UNKNOWN
: The status is not known or specified.INITIATED
: The import has been initiated.PARSING
: The system is currently parsing the import file.PARSED
: The import file has been successfully parsed.IMPORTING
: The system is currently importing the parsed data.IMPORTED
: The import process is complete.FAILED
: The import process has failed.The following table shows field support for filters and sorting for the Loyalty Import object:
Field | Query Filter Operators | Sortable |
---|---|---|
createdDate | $eq , $ne , $hasSome , $lt , $lte , $gt , $gte , $in , $nin , $exists | Sortable |
updatedDate | $eq , $ne , $hasSome , $lt , $lte , $gt , $gte , $in , $nin , $exists | Sortable |
status | $eq , $ne , $hasSome , $in , $nin , $exists | Sortable |
Related content: API Query Language, Query Loyalty Imports endpoint
An Import object is a batch import of loyalty points for existing customers. You can use Loyalty Imports to import loyalty points from 3rd-party providers or update existing customer point balances. This object tracks the entire import process from file upload to data processing.
The ID of the import.
ID of the asynchronous import job associated with this import.
Revision number, which increments by 1 each time the Loyalty Import is updated. To prevent conflicting changes, the current revision must be passed when updating the Loyalty Import.
Ignored when creating a Loyalty Import.
Date and time the Loyalty Import was created.
Date and time the Loyalty Import was last updated.
Current status of the import process.
Metadata of the uploaded file containing loyalty points data.
Results of parsing the uploaded file, including the number of rows parsed and any parse errors.
Results of the import process, including success and failure counts.
{
"loyaltyImport": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"revision": "1",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z",
"status": "INITIATED",
"fileMetadata": {
"size": 20915,
"name": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"url": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"sampleDataRows": []
},
"parseResult": {
"parsedRowCount": 0
},
"importResult": {
"errorFileExists": false
}
}
}
Retrieves a loyalty import.
You can only call this method when authenticated as a Wix app or Wix user identity.
Loyalty import ID.
Retrieved loyalty import.
curl -X GET \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports?loyaltyImportId=5cc0b472-e488-4de3-92ba-bd718a44933a' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{
"loyaltyImport": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"revision": "3",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:01.494Z",
"status": "PARSED",
"fileMetadata": {
"size": 20915,
"name": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"url": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"header": {
"values": ["name", "surname", "email", "points"]
},
"sampleDataRows": [
{
"values": ["Ray", "Alvarado", "aray6720@example.com", "15"]
},
{
"values": ["Charde", "Clemons", "c.clemons5125@example.com", "15"]
},
{
"values": ["Jade", "Matthews", "mjade1457@example.com", "15"]
},
{
"values": ["Xander", "Lucas", "lucas-xander665@example.com", "15"]
},
{
"values": ["Thaddeus", "Molina", "molina-thaddeus@example.com", "15"]
}
]
},
"parseResult": {
"parsedRowCount": 500
},
"importResult": {
"errorFileExists": false
}
}
}
Creates an import object based on an uploaded file.
Call this method after uploading your file to the URL obtained from Create Loyalty Import File Url.
You can only call this method when authenticated as a Wix app or Wix user identity.
URL of the file to import.
Name of the file to import.
Size of the file to import, in bytes.
Created loyalty import.
curl -X POST \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"fileUrl": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"fileName": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"fileSize": 20915
}'
{
"loyaltyImport": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"revision": "1",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T10:58:00.100Z",
"status": "INITIATED",
"fileMetadata": {
"size": 20915,
"name": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"url": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"sampleDataRows": []
},
"parseResult": {
"parsedRowCount": 0
},
"importResult": {
"errorFileExists": false
}
}
}
Retrieves the download URL for the error file of a failed loyalty import.
If an import fails, the importResult.errorFileExists
field in the LoyaltyImport
object is set to true
.
Use this method to get the URL of the error file, which contains details about which items couldn't be imported and why.
You can only call this method when authenticated as a Wix app or Wix user identity.
Loyalty import ID.
URL for downloading the error file.
curl -X GET \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/error-file-download-url?loyaltyImportId=bfc3f48e-4982-4977-a7a3-52bab9078a2d' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json'
{
"url": "https://wixmp-36bf13e0f0298791da8f320a.wixmp.com/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/f8278cb9-c014-422c-b5a9-ab0a9d7a5e14_errors.csv?token=example_x7zsjcXaTSa3ws1NcXTjk92m639yOkdUBa8DbuDZGoY&filename=import_errors_summary.csv"
}
Starts the actual import process for a loyalty import.
Call this method after the loyalty import object reaches the PARSED
status.
You can only call this method when authenticated as a Wix app or Wix user identity.
Loyalty import ID.
Header mapping information for the import file.
Executed loyalty import.
curl -X POST \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/execute' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"loyaltyImportId": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"headerMappingInfo": {
"headerMappings": [
{
"columnName": "EMAIL",
"columnIndex": 2
},
{
"columnName": "POINTS",
"columnIndex": 3
}
]
}
}'
{
"loyaltyImport": {
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"asyncImportJobId": "a9ff8502-cb2d-43dc-a7b3-981c8163f302",
"revision": "4",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T11:05:02.022Z",
"status": "IMPORTING",
"fileMetadata": {
"size": 20915,
"name": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"url": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"header": {
"values": ["name", "surname", "email", "points"]
},
"headerMappingInfo": {
"headerMappings": [
{
"columnName": "EMAIL",
"columnIndex": 2
},
{
"columnName": "POINTS",
"columnIndex": 3
}
]
},
"sampleDataRows": [
{
"values": ["Ray", "Alvarado", "aray6720@example.com", "15"]
},
{
"values": ["Charde", "Clemons", "c.clemons5125@example.com", "15"]
},
{
"values": ["Jade", "Matthews", "mjade1457@example.com", "15"]
},
{
"values": ["Xander", "Lucas", "lucas-xander665@example.com", "15"]
},
{
"values": ["Thaddeus", "Molina", "molina-thaddeus@example.com", "15"]
}
]
},
"parseResult": {
"parsedRowCount": 500
},
"importResult": {
"errorFileExists": false
}
}
}
Creates a URL for uploading a loyalty import file.
This method is the first step in the loyalty import process. It returns a file path and an upload URL, which you'll use in subsequent steps of the import process.
You can only call this method when authenticated as a Wix app or Wix user identity.
Path where the file will be stored.
URL for uploading the loyalty import file.
curl -X POST \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/wixmp-upload-url' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{}'
{
"filePath": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"uploadUrl": "https://upload.wixmp.com/upload/example_eccI15IeIinubB3btjWY"
}
Retrieves a list of loyalty imports, given the provided paging, filtering, and sorting.
To learn about working with query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
You can only call this method when authenticated as a Wix app or Wix user identity.
Filter object. See API Query Language for more information.
For a detailed list of supported filters, see Supported Filters.
List of loyalty imports matching the query.
Paging metadata.
curl -X POST \
'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"query": {}
}'
{
"loyaltyImports": [
{
"id": "5cc0b472-e488-4de3-92ba-bd718a44933a",
"asyncImportJobId": "a9ff8502-cb2d-43dc-a7b3-981c8163f302",
"revision": "6",
"createdDate": "2024-09-17T10:58:00.100Z",
"updatedDate": "2024-09-17T11:05:12.714Z",
"status": "IMPORTED",
"fileMetadata": {
"size": 20915,
"name": "data-8NkK3PqxWwQlOBzFF3izU.csv",
"url": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv",
"header": {
"values": ["name", "surname", "email", "points"]
},
"headerMappingInfo": {
"headerMappings": [
{
"columnName": "EMAIL",
"columnIndex": 2
},
{
"columnName": "POINTS",
"columnIndex": 3
}
]
},
"sampleDataRows": [
{
"values": ["Ray", "Alvarado", "aray6720@example.com", "15"]
},
{
"values": ["Charde", "Clemons", "c.clemons5125@example.com", "15"]
},
{
"values": ["Jade", "Matthews", "mjade1457@example.com", "15"]
},
{
"values": ["Xander", "Lucas", "lucas-xander665@example.com", "15"]
},
{
"values": [
"Thaddeus",
"Molina",
"molina-thaddeus@example.com",
"15"
]
}
]
},
"parseResult": {
"parsedRowCount": 500
},
"importResult": {
"errorFileExists": false,
"successCount": 500,
"failureCount": 0
}
}
],
"pagingMetadata": {
"count": 1,
"cursors": {},
"hasNext": false
}
}
Triggered when a loyalty import 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.imports.v1.loyalty_import
.
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.imports.v1.loyalty_import_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": "52269077-05f2-4b59-ba4f-36ef8c4c1e11",
"entityFqdn": "wix.loyalty.imports.v1.loyalty_import",
"slug": "created",
"entityId": "8046df3c-7575-4098-a5ab-c91ad8f33c47",
"createdEvent": {
"entityAsJson": "{\"loyaltyImport\":{\"id\":\"8046df3c-7575-4098-a5ab-c91ad8f33c47\",\"revision\":1,\"createdDate\":\"2019-10-30T17:22:10.299Z\",\"updatedDate\":\"2019-10-30T17:22:10.299Z\",\"loremUppercase\":\"LOREM UPPERCASE\",\"ipsum\":\"lorem ipsum\",\"businessAddress\":\"Pankivska 14a\"}}"
},
"eventTime": "2020-10-18T13:40:58.304800Z",
"triggeredByAnonymizeRequest": false
}