For the complete documentation index, see llms.txt. This page is also available as Markdown.

Unit Transfers

How to add or deduct points and loyalty units in bulk using XML or JSON imports in Open Loyalty.

Open Loyalty provides two separate import types for unit transfers:

  • Adding — grants units to members (e.g., migration balances, promotional bonuses, corrections)

  • Spending — deducts units from members (e.g., manual redemptions, balance corrections)

Each type is imported separately from the admin panel. Both use the same file structure — the system determines whether points are added or deducted based on which import type you select, not the values in the file.

File format: XML or JSON

Adding unit transfers

Use this import to grant units to members. Each record in the file will create an "Adding" transfer visible in the member's unit history.

1KB
Open
2KB
Open
unit-transfers-adding-sample.xml
<?xml version="1.0" encoding="UTF-8"?>
<transfers>
  <transfer>
    <customerId>e82c96cf-32a3-43bd-9034-4df343e5fd93</customerId>
    <points>500</points>
    <comment>Migration - initial balance</comment>
  </transfer>
  <transfer>
    <customerId>a1b2c3d4-e5f6-7890-abcd-ef1234567890</customerId>
    <points>1000</points>
    <comment>Promo: Summer 2025 bonus</comment>
  </transfer>
</transfers>

Spending unit transfers

Use this import to deduct units from members. Each record will create a "Spending" transfer visible in the member's unit history.

555B
Open
501B
Open

Points values are always positive. You do not need to use negative numbers. The import type you select in the admin panel (Adding or Spending) determines whether the points are granted or deducted.

Field reference

Field
Required
Description

customerId

Yes

Member UUID — the internal Open Loyalty identifier

points

Yes

Number of points to add or spend (always a positive number)

comment

No

A note explaining the transfer (visible in the member's point history)

Important notes

Include a meaningful comment. The comment appears in the member's point history and helps with auditing. Use descriptive values like Migration - initial balance or Promo: Summer 2025 bonus.

Common use cases

  • Data migration — set initial point balances when migrating to Open Loyalty (adding)

  • Bulk promotional grants — award bonus points to a group of members (adding)

  • Balance corrections — fix incorrect balances after a system error (adding or spending)

  • Manual bulk redemptions — deduct points for offline rewards or store credit (spending)

Common mistakes

Mistake
Fix

Using email instead of UUID

The customerId field requires the Open Loyalty member UUID

Uploading a spending file as an adding import (or vice versa)

Double-check which import type you select in the admin panel — the file format is the same for both

Importing very large files at once

Split into batches of 5,000–10,000 records

To find out more, please refer to the article below:

Importing Unit Transfers

Last updated

Was this helpful?