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.

Adding.json

1KB

Open

Adding.xml

2KB

Open

XML

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>

JSON

unit-transfers-adding-sample.json

[
  {
    "customerId": "e82c96cf-32a3-43bd-9034-4df343e5fd93",
    "points": 500,
    "comment": "Migration - initial balance"
  },
  {
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "points": 1000,
    "comment": "Promo: Summer 2025 bonus"
  }
]

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.

Spending.json

555B

Open

Spending.xml

501B

Open

XML

unit-transfers-spending-sample.xml

<?xml version="1.0" encoding="UTF-8"?>
<transfers>
  <transfer>
    <customerId>e82c96cf-32a3-43bd-9034-4df343e5fd93</customerId>
    <points>200</points>
    <comment>Balance correction - Q1 audit</comment>
  </transfer>
  <transfer>
    <customerId>a1b2c3d4-e5f6-7890-abcd-ef1234567890</customerId>
    <points>50</points>
    <comment>Manual redemption - store credit</comment>
  </transfer>
</transfers>

JSON

unit-transfers-spending-sample.json

[
  {
    "customerId": "e82c96cf-32a3-43bd-9034-4df343e5fd93",
    "points": 200,
    "comment": "Balance correction - Q1 audit"
  },
  {
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "points": 50,
    "comment": "Manual redemption - store credit"
  }
]

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

Unit transfers require Open Loyalty UUIDs. Unlike transactions (which accept email or phone), unit transfers only work with the internal member ID. Use the Members export to get the correct UUIDs.

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