Skip to main content

Customers

Your loyalty program members. Understanding how to model, segment, and engage customers is the foundation of a successful program.

The Customer Identity Model​

Every customer in Loyali has a unified identity that connects their activity across all your touchpoints:

Core Identity​

  • Email — Primary identifier, unique per organization
  • External Reference — Your user ID from your system (crucial for integration)
  • Profile Data — Name, phone, and other contact info

Loyalty Profile​

  • Points Balance — Current redeemable points
  • Lifetime Points — Total ever earned (determines tier status)
  • Current Tier — Their status level and benefits
  • Activity History — Full audit trail of all interactions

Custom Data​

  • Metadata — Any JSON data you want to store (preferences, segments, flags)

The External Reference: Your Integration Key​

The external_reference field is the most important field for integration. This is where you store YOUR user ID.

Why It Matters​

When a user logs into your app, you have their user ID but not their Loyali customer ID. The external reference lets you instantly look up their loyalty profile.

Without external reference:

  1. User logs in → You have user_123
  2. Search Loyali by email
  3. Hope the email matches
  4. Multiple API calls, potential mismatches

With external reference:

  1. User logs in → You have user_123
  2. One API call: GET /customers/external/user_123
  3. Instant access to their loyalty profile

Best Practice​

Always set external_reference when creating customers:

// When user signs up
createLoyaliCustomer({
  email: user.email,
  first_name: user.firstName,
  external_reference: user.id.toString()  // Your user ID
});

Customer Segmentation Strategy​

Use the metadata field to power segmentation without building custom infrastructure.

Behavioral Segments​

Track customer behavior for targeted campaigns:

Metadata KeyPurposeExample Values
signup_sourceAttribution"website", "mobile_app", "referral"
last_purchase_dateRecencyISO date string
purchase_countFrequencyNumber
lifetime_valueMonetaryDollar amount
preferred_categoryPreference"electronics", "fashion"

RFM Segmentation​

Build Recency-Frequency-Monetary segments:

  • Champions — High recency, high frequency, high value
  • Loyal Customers — High frequency, respond to promotions
  • At Risk — Were good customers, haven't purchased recently
  • Hibernating — Low on all metrics, need reactivation

Lifecycle Stages​

Track where customers are in their journey:

StageTriggerAction
NewJust signed upWelcome bonus, onboarding emails
ActiveRegular activityEngagement campaigns
At Risk30+ days inactiveWin-back offers
Churned90+ days inactiveReactivation campaigns

Customer Lifecycle Management​

Onboarding New Members​

The first 7 days determine long-term engagement:

  1. Welcome Bonus — Immediate gratification (50-100 points)
  2. First Action Reward — Bonus for completing profile, first purchase
  3. Education — Show them how to earn and what they can redeem
  4. Goal Setting — Show progress toward first tier/reward

Engagement Loop​

Keep customers active with:

  • Milestone Celebrations — "You've earned 1,000 points!"
  • Progress Updates — "You're 200 points from Silver!"
  • Personalized Offers — Based on their preferences
  • Surprise & Delight — Unexpected bonus points

Win-Back Campaigns​

For inactive customers:

  1. Reminder — "Your 500 points are waiting"
  2. Incentive — "Earn 2x points this week only"
  3. Urgency — "Your points expire in 30 days"
  4. Final Offer — "We miss you - here's 100 bonus points"

Data Privacy & Compliance​

GDPR Considerations​

  • Customers can request data export
  • Customers can request deletion (right to be forgotten)
  • Store only necessary data
  • Get consent before marketing communications

What NOT to Store​

Never put these in customer records or metadata:

  • Passwords or authentication tokens
  • Full payment card numbers
  • Social security numbers
  • Sensitive health information

Data Retention​

Consider policies for:

  • Inactive account cleanup
  • Points expiration notices
  • Transaction history retention

Common Integration Patterns​

Pattern 1: Signup Sync​

Create loyalty profile when user signs up:

User signs up in your app
    ↓
Create customer in Loyali (with external_reference)
    ↓
Award welcome bonus
    ↓
Show loyalty status in your app

Pattern 2: Find or Create​

Handle existing users who may or may not have loyalty profiles:

User logs in
    ↓
Try to find by external_reference
    ↓
Found? → Load their profile
Not found? → Create new profile
    ↓
Continue with loyalty features

Pattern 3: Profile Sync​

Keep customer data in sync between systems:

User updates profile in your app
    ↓
Update Loyali customer with new data
    ↓
Both systems stay consistent

Dashboard vs API​

TaskDashboardAPI
View customer details✅ Click to explore✅ GET endpoints
Add individual customer✅ Form-based✅ POST request
Bulk import❌ Use API✅ Batch requests
Real-time sync❌ Manual✅ Automated
Customer lookup✅ Search bar✅ Multiple lookup methods

Next Steps​