Get Customer

Use these endpoints whenever the POS, e-commerce, app, or middleware must resolve which Loyal Guru Customer is in context before sending a cart, selecting a voucher, or deciding whether to enroll a new profile.

Wrong or ambiguous identification is the most common root cause of “voucher not available”, split points, and duplicate Customers.

When to use which call

Need	Endpoint	Notes
Resolve one Customer by a known key	GET /customers/{value}	{value} can be id, email, phone, or code (depending on Company configuration and payload)
Fetch several Customers by IDs or phones	GET /customers	At least one filter (IDs or phones) is required
Find Customers when the key is uncertain	POST /customers/search	Search by profile fields; then confirm ownership before merge or update

OpenAPI schemas: Customer endpoints · API Reference

Identification at checkout

Practical rules

1. Prefer the same external ID the retailer uses across channels (see Overview unified pattern).
2. If the channel only has email or phone, call search or GET by that value, then store the returned Loyal Guru Customer ID for subsequent carts.
3. Before creating a new Customer on conflict, search and decide whether to update, merge, or associate.
4. Never silently pick the first search hit for a merge without identity verification.

GET /customers/{value}

Purpose: load one Customer profile for runtime use.

Typical uses:

• POS scans a loyalty card / code and needs the Customer before POST /carts/simulate.
• App opens a session and refreshes profile, tiers, or consent-related fields.
• Middleware validates that a voucher owner matches the Customer at checkout.

Implementation notes:

• Use the identifier type your Company agreed during onboarding (numeric id, code, email, or phone).
• Treat 404 / not-found as “no Customer yet” and route to enrollment — not as a hard failure unless the flow requires an enrolled Customer.
• Cache carefully: profile, vouchers, and balances can change after merges or redemptions.

GET /customers (list)

Purpose: retrieve a small set of Customers by IDs or phones in one call.

Use when the middleware already knows several keys (for example batch reconciliation) and needs matching LG profiles. Prefer GET-by-value for single interactive checkouts.

POST /customers/search

Purpose: find Candidates when the channel has partial identity data.

Use when:

• Deduplicating before create (email/phone already exists).
• Support tools look up a Customer by name or alternate field.
• Preparing a merge after detecting possible duplicates.

After search:

1. Present or auto-select only when confidence is high.
2. Verify ownership (OTP, in-store ID, SSO) before merge.
3. If uncertain, create a soft association instead of consolidating benefits.

Related flows

Next step	Guide
Customer does not exist	Create and Update
Two Customers are the same person	Merge
Link without pooling benefits	Associations and Cards

Troubleshooting

Symptom	What to check
Voucher not available for this Customer	Channel may be using a different identifier than the one that owns the voucher — GET the Customer used on the cart and compare.
Search returns multiple hits	Do not auto-merge; verify ownership or use association.
GET works with email but carts fail	Cart may still send a different customer_id / code — align keys.
Works in app, fails in POS	Online and offline databases may have created two Customers — see Merge.