Merge Customers
Use merge when two Customer records represent the same person (or a household that must pool loyalty benefits) and the integration must consolidate points, vouchers, challenges, and history onto one surviving account.
Merges are irreversible for day-to-day ops in most projects — verify identity before calling them.
Endpoints
| Action | Endpoint | When to use |
|---|---|---|
| Merge one Customer into another | POST /customers/transfer | Both accounts already exist; keep the destination Customer ID |
| Merge by creating a new Customer | POST /customers/transfer-new | Build a new surviving Customer and move data into it |
| Unmerge | POST /customers/{associate_id}/unmerge | Undo a previous merge/association when the API and Company support it |
OpenAPI: Customer endpoints · API Reference
When to merge vs associate
| Goal | Use |
|---|---|
| One person, two enrollments (online + offline) | Merge after verification |
| Family/cards share points and vouchers | Merge into household main account |
| Link accounts but keep separate balances | Soft association — see Associations and Cards |
| Identity not verified yet | Soft association or wait — do not merge |
Deduplication patterns
Middleware or IAM orchestrates merge
Touchpoints create Customers independently. A middleware detects duplicates, verifies the match, then calls transfer.
Until the merge runs, points and vouchers can be split across A and B.
Touchpoint orchestrates merge
The channel searches before create; on conflict it verifies ownership and merges immediately. See also Get Customer and Create and Update.
:::caution Fraud risk Do not merge based only on matching email or phone. An attacker can register with another Customer's unverified email and take over points and vouchers if the touchpoint merges automatically. Require OTP or equivalent checks. If identity is uncertain, use a soft association instead. :::
Households — pooled benefits
When several cards or family members should share loyalty benefits, merge card accounts into a main household Customer. Transactions from any card can feed the main balance; individual card history can still be used for reporting.
| Option | Flow |
|---|---|
| Both accounts exist | Create/get both, then transfer card → main |
| New card for existing household | Add card on the main Customer, or create then merge |
| First registration + card | Create main Customer and card relationship in one registration flow where supported |
After a strong household merge, the merged card should not accrue points independently.
Full scenario context (ecomm vs offline IDs, unified database, soft association): Customer Data overview.
POST /customers/transfer
Moves loyalty state from a source Customer into a destination Customer that already exists. Use when the surviving ID must stay stable (for example the e-commerce Customer ID).
POST /customers/transfer-new
Creates a new Customer and consolidates into it. Use when neither existing ID should remain, or onboarding defines a new master ID.
POST /customers/{associate_id}/unmerge
Splits a previously merged or associated relationship when supported. Confirm behavior with the Loyal Guru team for your Company before relying on unmerge in production runbooks.
Loyalty impact checklist
Before any merge, validate impact on:
- Points and wallet balance
- Active and selected vouchers
- Reward transactions
- Challenge progress and game history
- Audiences and calculated attributes
- Cart history and discount reports
- Consent and communication preferences
Related flows
| Situation | Guide |
|---|---|
| Resolve candidates first | Get Customer |
| Link without pooling benefits | Associations and Cards |
| Pattern overview | Customer Data overview |
Troubleshooting
| Symptom | What to check |
|---|---|
| Points on the wrong account after merge | Source/destination IDs reversed; merge without OTP |
| Challenge progress disappeared | Customer was recreated instead of merged, or wrong survivor ID |
| Household expected separate balances | Strong merge was used — switch to soft association |
| Duplicate benefits until merge runs | Expected in middleware-orchestrated dedup — shorten the window or merge at touchpoint |
| Unmerge did not restore state | Confirm Company support and which side effects are reversible |