Introduction

The Loyalty Imports API allows you to import loyalty data from external sources into your Wix site's loyalty program, track import progress, and handle any errors that may occur during the process.

With the Loyalty Imports API, you can:

• Create a loyalty import to initiate the import process.
• Create a loyalty import file URL to securely upload loyalty data files.
• Execute the loyalty import to begin processing the uploaded file.
• Get a loyalty import to retrieve details about a specific import.
• Get an error file download URL to access error information for failed imports.
• Query loyalty imports to retrieve and filter existing loyalty imports.

Import Process Overview

The loyalty import process follows these steps:

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

Loyalty Data Import

The Loyalty Imports API allows you to import loyalty data for existing customers. Typically, this data includes:

• Customer email addresses
• Loyalty point balances

Sample Import File

Here's an example of what your import file might look like:

When preparing your import file, keep these points in mind:

• The file must contain at least two required fields:
  • A field with the customer's email address.
  • A field with the customer's points balance.
• You can include additional fields, but they won't affect the import.
• The email addresses in the file must match those of existing customers 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

You can find this information in the importResult property of the Loyalty Import object:

• 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 rows and 1 fails to import, the response might look like this:

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, use the GetErrorFileDownloadUrl method 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.

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.

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.