> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/main-features/imports-exports/imports/sample-import-files/unit-transfers.md).

# Unit Transfers

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.

{% file src="/files/Inl8dUkvaxUBRWSbZGQF" %}

{% file src="/files/FslA3IHjjLZtNrScym2k" %}

{% tabs %}
{% tab title="XML" %}
{% code title="unit-transfers-adding-sample.xml" %}

```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>
```

{% endcode %}
{% endtab %}

{% tab title="JSON" %}
{% code title="unit-transfers-adding-sample.json" %}

```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"
  }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

{% file src="/files/W4KJtHtvUkFbJha6oONp" %}

{% file src="/files/XJIxi9jLGCEHM2cahYZx" %}

{% tabs %}
{% tab title="XML" %}
{% code title="unit-transfers-spending-sample.xml" %}

```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>
```

{% endcode %}
{% endtab %}

{% tab title="JSON" %}
{% code title="unit-transfers-spending-sample.json" %}

```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"
  }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**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.
{% endhint %}

### Field reference

<table><thead><tr><th width="138.1015625">Field</th><th width="133.5859375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customerId</code></td><td>Yes</td><td>Member UUID — the internal Open Loyalty identifier</td></tr><tr><td><code>points</code></td><td>Yes</td><td>Number of points to add or spend (always a positive number)</td></tr><tr><td><code>comment</code></td><td>No</td><td>A note explaining the transfer (visible in the member's point history)</td></tr></tbody></table>

### Important notes

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
**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`.
{% endhint %}

### 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:

{% content-ref url="/pages/qwA7UHhCc9ItQJPvYZkP" %}
[Importing Unit Transfers](/main-features/wallets/unit-transfers/importing-unit-transfers.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.openloyalty.io/main-features/imports-exports/imports/sample-import-files/unit-transfers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.