Importing Unit Transfers

In this article, you’ll learn how to import unit transfers into Open Loyalty.

Overview

Importing unit transfers lets you upload many unit adjustments at once rather than entering them one by one. This is especially helpful when you’re working with large volumes of changes — for example when syncing data from another system, applying historic adjustments, or correcting many accounts in

bulk.

---

Why use imports

Importing gives you:

• Faster processing of a large number of transfers

• Reduced manual effort and human errors

• Consistent, repeatable updates to member balances

It’s a practical way to manage many units at once without having to create individual transfers manually.

---

Prerequisites

Before you begin, make sure you have the following:

1. Open Loyalty Admin Access You must be logged into the Admin Panel with permission to import data.

2. Correct File Format: JSON or XML Only JSON and XML are accepted by OpenLoyalty for importing unit transfers.

3. Sample File Structure Review the structure of JSON and XML files provided below to understand how to format your adding or spending (deducting) transfers. You can find these files under the link below.

Sample Import Files

---

Types of imports

You can import two main kinds of unit transfers:

• Adding units — Used when you want to award points or credits

• Spending / Deducting units — Used when removing units from member wallets

Make sure your file clearly identifies which transfers are additions and which are deductions.

---

Understanding the Import File

OpenLoyalty supports two key scenarios when importing unit transfers:

1. Adding Units (e.g., awarding units)

2. Spending or Deducting Units (e.g., redeeming units)

Your JSON or XML file needs to include fields such as:

• Customer ID (required) The unique identifier of the loyalty account to which the transfer applies.

Use the identifier generated by Open Loyalty.

First, you might need to match your internal identifier (such as email, phone number, or loyalty card number) to the corresponding member ID in Open Loyalty.

• Units (points) (required) The number of units that need to be added or deducted.

• Wallet (walletTypeCode) (required) The code of the wallet the units need to be added to or deducted from.

• Date (registeredOn) (optional) The date of the transfer, typically in YYYY-MM-DD HH:mm:ss format. If not specified, the registeredOn date will be saved as the date of unit transfer creation.

• Expire Date (optional)

  You can define the expiry date for units in two ways:

  • expireAt: Specifies the exact date and time of expiry.

  • expiresInDays: Indicates how many days from the registration date the units will remain available.

• Pending Date (optional)

  You can define the pending (lock) date for units in the following way:

  • lockedUntilDays: Indicates how many days from the registration date the units will remain pending (locked).

• Comment (optional) Any additional text or comments about this unit transfer.

For detailed structures, please refer to the JSON and XML example files above.

---

How to Import Unit Transfers

Below is a step-by-step guide on how to import your unit transfers:

1. Navigate to the Import Section

1. In the OpenLoyalty Admin Panel, go to Wallets, then Unit transfers.

2. Select the down arrows next to the Unit transfers and select the relevant Import transfers option.

1. Click Click to upload or drag and drop a file.

2. Click on Import units transfers.

2. Check the Import Results

1. You can find the list of imported files under Imports / Exports menu option, in the Imports tab.

2. If there are errors, you can filter them out and validate the results.

---

Troubleshooting and Common Issues

• Invalid File Format If you attempt to upload a non-supported file type (like CSV), the system will likely reject it. Make sure you only upload JSON or XML.

• Date/Time Format Ensure your dates are in a format OpenLoyalty accepts (often YYYY-MM-DD HH:mm:ss).

• Invalid Account IDs The import will fail if an account ID doesn’t exist in the system. Make sure the correct accounts are set up, or update your file to reflect valid IDs.

• Insufficient Permissions Only users with the right roles (e.g., Admin or specific Import/Export permissions) can perform imports. Check your user role if you don’t see the import option.

---

Best practices

To make your imports reliable:

• Always map member identifiers correctly before importing.

• Start with a small test import to confirm everything is formatted properly.

• Use unique external transfer IDs when relevant to avoid duplicates.

• Include meaningful comments or custom attributes in the import data so it’s easy to identify why transfers were created.

---

After the import

Once the import completes:

• You can view the newly created unit transfers in the Unit Transfers List

• Use filters to check specific members, dates, or wallet types

• Review the logs for the import in Imports/Export section.

• Perform management actions (cancel, expire, block) as needed in the managing sub-article