Customer Data

Customer integration defines how an external system creates, identifies, updates, and reconciles Loyal Guru customers. Getting this right is critical because discounts, points, vouchers, rewards, games, challenges, and audiences all depend on the customer identity used at runtime.

The target state is simple: every loyalty action should be associated with one stable Customer ID, and Loyal Guru must be notified whenever two identities are consolidated. When a retailer cannot use one Customer ID across POS, e-commerce, app, and physical card systems, the integration must explicitly choose how duplicates, cards, and relationships are handled.

Guides in this section

Guide	Use it for
Get Customer	Look up a Customer by ID, email, phone, or code; list and search before checkout or enrollment
Create and Update	Enroll, update profile fields, and delete/anonymize
Merge	Consolidate duplicates, households, transfer/unmerge, and fraud safeguards
Associations and Cards	Soft links between accounts, loyalty cards, and card renewal

Schemas and auth: Customer endpoints · API Reference · API Keys

Identity flow

Implementation patterns (summary)

Pattern	When to use	Primary guides
Unified Customer ID	Same ID in POS, e-commerce, app, CRM	Create and Update, Get Customer
Separate online/offline	Independent enrollments per channel (different IDs)	Get Customer, Merge
Household (pooled benefits)	Family/cards share points and vouchers	Merge, Associations and Cards
Soft association	Link accounts without pooling benefits	Associations and Cards
Card renewal	Lost/replaced physical card	Associations and Cards, Merge

Unified database with one Customer ID

Use this when the retailer already has a single customer database and the same Customer ID is available in POS, e-commerce, app, CRM, and physical card systems.

In this model, the integration creates or updates the Customer once and all later actions reference the same ID directly. There is no merge logic, no card resolution, and no temporary split of points, vouchers, challenges, or transactions.

Use it when:

• The retailer has centralized SSO or a unified customer master.
• POS and digital channels can all send the same Customer ID.
• The business does not need household pooling or card replacement flows beyond normal profile updates.

Detail guides: Create and Update · Get Customer

Separate online and offline databases

Use this when a Customer can be created independently in more than one channel, for example an e-commerce account and a physical POS loyalty card with different IDs. The integration must decide who detects duplicates and who triggers the merge.

Option A — Middleware or IAM orchestrates deduplication

Touchpoints create Customers without blocking duplicate records. A middleware or IAM layer periodically or synchronously detects that two records represent the same person, validates the match, and tells Loyal Guru to merge the accounts.

This keeps POS and e-commerce simple, but duplicate loyalty accounts can exist until the middleware runs. During that window, points, vouchers, rewards, and challenge progress may be split.

Option B — Touchpoint handles deduplication

The touchpoint checks uniqueness before creating the Customer. If it detects that an email, phone, or other unique field already exists, it creates or updates the operational record and triggers the merge directly.

This reduces the time that benefits are split, but every touchpoint must implement the same deduplication and verification logic.

:::caution Fraud risk Do not merge accounts based only on a matching email or phone unless ownership was verified. If an attacker registers with another Customer's unverified email and the touchpoint merges accounts automatically, points, vouchers, and rewards can be taken over. Use OTP or additional identity checks before calling merge endpoints. If identity cannot be trusted, create a soft association instead of consolidating loyalty benefits. Details: Merge. :::

Detail guides: Get Customer · Merge

Households — shared loyalty benefits

Use this when several cards or family members should share loyalty benefits. The main account remains active and associated card accounts are merged into it. Transactions from any card can contribute to the main balance while individual card usage can still be kept for reporting and segmentation.

Common setup options:

Option	When to use	Flow
Merge existing accounts	Both the household account and card account already exist.	Create both records, then merge the card into the main household account.
Add a new card to an existing household	The main household already exists and a new physical card is issued.	Create the new card directly linked to the existing Customer.
Create household and card together	First registration happens at a store and the card should be linked immediately.	Create the main Customer and card relationship in one registration flow where supported.

Use this model only when benefits should be pooled. Once a card is merged into the household, it should not accrue points independently.

Detail guides: Merge · Associations and Cards

Associations

Use associations when accounts should be linked for visibility, relationship tracking, segmentation, or support workflows, but each account must keep its own points, coupons, redemptions, and transaction history.

Typical cases:

• Family members with separate balances but shared visibility.
• Physical card and unconfirmed digital account, before identity is verified.
• Employee and customer accounts linked for traceability without mixing balances.

Associations are safer than merges when identity is uncertain because they do not consolidate benefits.

Detail guide: Associations and Cards

Card renewal

Use card renewal when a Customer loses a physical card or receives a replacement and must keep their loyalty history. The integration must verify the Customer's identity before replacing or transferring card ownership.

Option	When to use	Result
New card already exists	The replacement card is already registered as another Customer record.	Merge the old card account into the new card account after verification.
New card does not exist	The replacement card is brand new.	Create the replacement account and transfer the old account's data/history to it.

:::caution Identity verification Loyal Guru does not validate that the person requesting a card replacement owns the original account. The external system or store process must verify identity before calling transfer or card endpoints. :::

Detail guides: Associations and Cards · Merge

Internal WL App flows

Some Customer flows in the source material are specific to the Loyal Guru white-label app, such as digitizing a physical card through the app, using the LG App as IAM, or syncing app-created Customers to a retailer IAM by webhook. Treat these as WL App implementation topics, not generic public runtime API integration scenarios, unless the Loyal Guru team explicitly scopes them for the project. See WL App SDK.

Endpoint map

Action	Endpoint	Detail page
Get Customer	GET /customers/{value}	Get Customer
List by IDs or phones	GET /customers	Get Customer
Search	POST /customers/search	Get Customer
Create / enroll	POST /customers	Create and Update
Update	PATCH /customers/{value}	Create and Update
Delete / anonymize	DELETE /customers/{value}	Create and Update
Merge into another	POST /customers/transfer	Merge
Merge into new Customer	POST /customers/transfer-new	Merge
Unmerge	POST /customers/{associate_id}/unmerge	Merge
Associations	POST / PATCH / DELETE /associations	Associations and Cards
List associates	GET /customers/{id}/associates	Associations and Cards
Add card	POST /customers/{id}/cards	Associations and Cards

Loyalty impact checklist

Before changing customer identity or merging customers, validate the impact on:

• Points and wallet balance.
• Active vouchers and selected vouchers.
• Reward transactions.
• Challenge progress.
• Game availability and play history.
• Audiences and calculated attributes.
• Cart history and discount reports.
• Customer consent and communication preferences.

Troubleshooting

Symptom	What to check
Customer cannot use a voucher	The app/POS may be sending a different customer identifier than the one that owns the voucher.
Challenge progress disappeared after profile change	Verify whether the customer was merged, transferred, or recreated instead of updated.
Duplicate customers receive separate benefits	Confirm lookup keys and deduplication rules before enrollment.
Card renewal loses loyalty state	Use card addition/renewal flow instead of creating a new customer.
Points were consolidated into the wrong account	Check whether the merge was executed without OTP, ownership verification, or additional identity checks.
Household members expected separate balances	A strong household merge pools benefits. Use soft association when balances must remain independent.
Associated accounts do not share points	Associations are visibility-only. Use a merge/household model when benefits must be pooled.
Retailer IAM and Loyal Guru disagree after app registration	Confirm whether the flow is WL App-specific and whether customer sync webhooks are in scope for the project.