> 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/implementation-guide/data-and-go-live/data-migration.md).

# Data Migration

Moving members, balances, badges and progress from a previous loyalty system into Open Loyalty without paying anyone twice.

When a programme replaces an existing one, members expect to keep their account, balance and status. This page covers planning and running the migration so the numbers match and no campaign pays twice. For the import formats and order, see the User Guide's [Data migration guide](https://help.openloyalty.io/integrations-and-data-exchange/imports-exports/imports/data-migration-guide) and [Imports](https://help.openloyalty.io/integrations-and-data-exchange/imports-exports/imports).

## Who does what

| Area               | Responsibility                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Your team**      | Exports and cleans the data, writes and runs the migration job, signs off the reconciliation                                         |
| **Open Loyalty**   | Import tools and API; advice on order and volumes; a limits increase for large API migrations (request it from Open Loyalty support) |
| **Programme team** | Decides what carries over (balances, history, status, missions) and how members are told                                             |

## What to carry over

| Data                                         | How                                                                 | Notes                                                                                                                                                                    |
| -------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Members                                      | Import (`member`) or `POST /member`                                 | Keep the original `registeredAt` (anniversaries) and `birthDate`. Add a label such as `migrated = true`.                                                                 |
| Balances                                     | `POST /points/add` per member and wallet, or a unit-transfer import | One transfer per member and wallet with `externalTransferId` (e.g. `MIG-{id}-{wallet}`). Imports need the Open Loyalty member UUID. Decide the expiry of migrated units. |
| Lifetime totals                              | Labels or custom fields (e.g. `total_earned_migrated`)              | Only if tiers or messages need them.                                                                                                                                     |
| Tier                                         | Let tier conditions recalculate, or assign by hand                  | If old status must be honoured exactly, [assign the tier](https://help.openloyalty.io/implementation-guide/module-checklists/tiers.md) by hand.                          |
| Completed missions                           | `POST /member/{member}/badge`                                       | One badge per completed mission worth showing.                                                                                                                           |
| Mission progress                             | `PATCH /member/{member}/challenge/{challenge}/progress`             | Sets progress without paying milestone rewards.                                                                                                                          |
| Transaction history                          | Transaction import (optional)                                       | Matched by email, phone or loyalty card number. **Active purchase campaigns run on imported transactions.**                                                              |
| Webhooks, redemption statuses, custom events | Not importable                                                      | Set up or replay through the API.                                                                                                                                        |

## Recommended flow

{% stepper %}
{% step %}

### Protect against double rewards

Before importing: deactivate earning campaigns that would fire on migrated data (especially purchase campaigns, if you import transactions), and make welcome and lifecycle campaigns exclude migrated members (e.g. a condition on the `migrated` label).
{% endstep %}

{% step %}

### Rehearse on staging

Run the full migration on staging with a copy of the data — anonymised, since staging shouldn't hold real personal data. Time it, fix rejects, and agree the reconciliation numbers.
{% endstep %}

{% step %}

### Import members

Import members first, each with an identifier the previous system and Open Loyalty share: `email`, `phone` or `loyaltyCardNumber`, whichever is the store's identification method. Later imports match on it: the [Member Custom Fields import](https://help.openloyalty.io/integrations-and-data-exchange/imports-exports/imports/sample-import-files/member-custom-fields) accepts email, phone, loyalty card number or member UUID. The member import file carries no custom field values, so while an active member custom field is required every row is rejected: deactivate required member fields for the import and fill them afterwards with the Member Custom Fields import. Then get their Open Loyalty UUIDs — from the API responses or a [members export](https://help.openloyalty.io/integrations-and-data-exchange/imports-exports/exports/ui-exports) — for the steps that need them.
{% endstep %}

{% step %}

### Import balances, badges and progress

Add one unit transfer per member and wallet with a deterministic `externalTransferId`: if the job is re-run, existing transfers are rejected instead of doubled. Then badges and challenge progress.
{% endstep %}

{% step %}

### Reconcile

Compare member counts and balance totals per wallet between the source and Open Loyalty, plus a sample of individual members. Investigate every difference before going live.
{% endstep %}

{% step %}

### Switch on

Activate the campaigns that were paused, then switch the channels over — see the [go-live checklist](https://help.openloyalty.io/implementation-guide/data-and-go-live/go-live-checklist.md).
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-7869b50345113c1c75336393ff1f09f82705b195%2Fig-data-migration.png?alt=media" alt="Before migrating, earning campaigns that must not pay twice are inactive and welcome campaigns exclude members labelled migrated. The migration job exports from the previous system and imports members with their original registration date and a migrated label, getting each customerId. It adds balances per member and wallet with an externalTransferId, so a re-run is rejected rather than doubled. It adds badges and sets challenge progress without paying rewards. Optionally it imports historical transactions, which active purchase campaigns would run on. It reconciles counts and balance totals per wallet, then campaigns are activated and channels switched over." width="698"><figcaption><p>A migration run</p></figcaption></figure>

## Volumes and limits

* Import files are limited to 100 MB, and up to 5 imports or exports can run at the same time — see [Limits](https://help.openloyalty.io/technical-guide/api-fundamentals/limits).
* For an API-based migration of many members, throttle the job below the environment's soft limit and request a limits increase from Open Loyalty support in advance.

## Checklist

* [ ] What carries over (balances, totals, tier, missions, history) is agreed and written down.
* [ ] Welcome and lifecycle campaigns exclude migrated members.
* [ ] Campaigns that would fire on imported data are paused during the migration.
* [ ] The migration has been rehearsed on staging with anonymised data.
* [ ] Every balance transfer has a deterministic `externalTransferId`.
* [ ] Original registration and birth dates are kept.
* [ ] Member counts and balance totals reconcile per wallet.
* [ ] Members are told what was carried over.

## Key endpoints

* `POST /api/{storeCode}/import/{type}` — [Import file](https://help.openloyalty.io/api-reference/import/import-file)
* `POST /api/{storeCode}/member` — [Add a member](https://help.openloyalty.io/api-reference/member/add-a-member)
* `POST /api/{storeCode}/points/add` — [Add an units transfer](https://help.openloyalty.io/api-reference/points/add-an-units-transfer)
* `POST /api/{storeCode}/member/{member}/badge` — [Add badge to member](https://help.openloyalty.io/api-reference/badge/add-badge-to-member)
* `PATCH /api/{storeCode}/member/{member}/challenge/{challenge}/progress` — [Update challenge progress for member](https://help.openloyalty.io/api-reference/campaign/update-challenge-progress-for-member)
* `POST /api/{storeCode}/export/{type}` — [Create an export](https://help.openloyalty.io/api-reference/export/create-an-export)

{% hint style="warning" %}
**Common pitfalls**

* Importing historical transactions while purchase campaigns are active: members are paid again for old purchases.
* Forgetting the `migrated` guard: every migrated member gets the welcome reward.
* Re-running a failed migration without stable `externalTransferId`s: balances double.
* Setting `registeredAt` to the migration date: every anniversary reward fires on the same day.
* Importing members while a member custom field is required: every row fails with `Field "…" in group "…" is required.`
  {% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/data-and-go-live/data-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
