Introduction

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.

Before you begin

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

  • You must have the Wix Loyalty Program app installed on your site to use this API.
  • The maximum file size for loyalty imports is 10MB.

Import process overview

The loyalty import process follows these phases:

  1. Prepare Data File: Create a CSV file with the required loyalty data fields.
  2. Create Upload URL: Generate a secure URL for file upload.
  3. Upload File: Upload your prepared loyalty data file to the provided URL.
  4. Create Import: Initialize the import process, which includes file parsing.
  5. Execute Import: Start the actual import of parsed data.
  6. Monitor Progress: Track the import status and handle any errors.

Preparing the loyalty data file

When creating your loyalty data file for import, consider the following guidelines:

Required fields

Your import file must contain at least two required fields:

  • A field with the customer's email address.
  • A field with the customer's points balance.

File format

Prepare your data in a CSV (Comma-Separated Values) format. Here's an example of what your import file might look like:

Copy
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

Additional considerations

  • The email addresses in the file must match those of existing contacts in your loyalty program.
  • The import will be successful as long as the required fields are present and formatted correctly.

Customer identification and error handling

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 process continues even if errors are encountered for individual customers.
  • Successful imports and errors are tracked separately.
  • After completion, you can retrieve error details for any failed imports.

The importResult property of the Loyalty Import object contains the results of the import:

  • successCount: Number of successfully imported customer records
  • failureCount: Number of customer records that couldn't be imported
  • errorFileExists: Indicates whether an error file is available for download

The parseResult property provides information about the initial file parsing:

  • parsedRowCount: Total number of rows processed from the import file

For example, if you import a file with 3 customers and 1 fails to import, the response might look like this:

Copy
{ "parseResult": { "parsedRowCount": 3 }, "importResult": { "errorFileExists": true, "successCount": 2, "failureCount": 1 } }

This indicates:

  • 3 rows were parsed from the file
  • Points for 2 customers were successfully imported
  • Points for 1 customer failed to import

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.

Terminology

  • Loyalty Import: A Loyalty Import represents 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.
  • Import Status: The current state of the import process. Possible values include:
    • 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.
  • Header Mapping Info: Information used to map headers in the import file to corresponding fields in the loyalty program.
  • Error File: A file containing details about errors encountered during the import process.
  • Parse: The process of analyzing the import file to ensure it's in the correct format and contains valid data before proceeding with the actual import.
Did this help?

Loyalty Imports: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Loyalty Import object:

FieldQuery Filter OperatorsSortable
createdDate$eq, $ne, $hasSome, $lt, $lte, $gt, $gte, $in, $nin, $existsSortable
updatedDate$eq, $ne, $hasSome, $lt, $lte, $gt, $gte, $in, $nin, $existsSortable
status$eq, $ne, $hasSome, $in, $nin, $existsSortable

Related content: API Query Language, Query Loyalty Imports endpoint

Did this help?

Loyalty Import Object


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.

Properties
idstringRead-onlyformat GUID

The ID of the import.


asyncImportJobIdstringRead-onlyformat GUID

ID of the asynchronous import job associated with this import.


revisionintegerRead-onlyformat int64

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.


createdDatestringRead-onlyformat date-time

Date and time the Loyalty Import was created.


updatedDatestringRead-onlyformat date-time

Date and time the Loyalty Import was last updated.


statusstringRead-only

Current status of the import process.


fileMetadataFileMetadata

Metadata of the uploaded file containing loyalty points data.


parseResultParseResult

Results of parsing the uploaded file, including the number of rows parsed and any parse errors.


importResultImportResult

Results of the import process, including success and failure counts.

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

GET

Get Loyalty Import


Retrieves a loyalty import.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports

Query Params
loyaltyImportIdstringRequired

Loyalty import ID.

Response Object
loyaltyImportLoyaltyImport

Retrieved loyalty import.

Request
cURL
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'
Response
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 } } }
Did this help?

POST

Create Loyalty Import


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports

Body Params
fileUrlstringRequired

URL of the file to import.


fileNamestring

Name of the file to import.


fileSizeintegerformat int32

Size of the file to import, in bytes.

Response Object
loyaltyImportLoyaltyImport

Created loyalty import.

Create Loyalty import
Request
cURL
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 }'
Response
JSON
{ "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 } } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Error File Download Url


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/error-file-download-url

Query Params
loyaltyImportIdstringRequired

Loyalty import ID.

Response Object
urlstring

URL for downloading the error file.

Get error file download URL
Request
cURL
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'
Response
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" }
Did this help?

POST

Execute Loyalty Import


Starts the actual import process for a loyalty import.

Call this method after the loyalty import object reaches the PARSED status.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/execute

Body Params
loyaltyImportIdstringRequired

Loyalty import ID.


headerMappingInfoHeaderMappingInfo

Header mapping information for the import file.

Response Object
loyaltyImportLoyaltyImport

Executed loyalty import.

Execute Loyalty import
Request
cURL
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 } ] } }'
Response
JSON
{ "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 } } }
Did this help?

POST

Create Loyalty Import File Url


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/wixmp-upload-url

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

Path where the file will be stored.


uploadUrlstring

URL for uploading the loyalty import file.

Create Loyalty import file url
Request
cURL
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 '{}'
Response
JSON
{ "filePath": "/sites/dbba027b-3ad1-49dc-abdc-e1167a75290b/6099ebc5-0cce-4a2b-9903-2429c214d757.csv", "uploadUrl": "https://upload.wixmp.com/upload/example_eccI15IeIinubB3btjWY" }
Did this help?

POST

Query Loyalty Imports


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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/query

Body Params
queryQueryRequired

Filter object. See API Query Language for more information.

For a detailed list of supported filters, see Supported Filters.

Response Object
loyaltyImportsArray <LoyaltyImport>

List of loyalty imports matching the query.


pagingMetadataPagingMetadata

Paging metadata.

Query Loyalty imports
Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/loyalty-imports/v1/loyalty-imports/query' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "query": {} }'
Response
JSON
{ "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 } }
Did this help?

Loyalty Import Created


Triggered when a loyalty import 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.imports.v1.loyalty_import.


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

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