A Loyalty Journey is an automated email flow that keeps customers informed about their points balance and engaged with your rewards program. It connects your existing loyalty system to OneSignal so personalized, data-driven messages go out automatically without manual campaign sends each week. This tutorial covers two implementation cases:Documentation Index
Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
Use this file to discover all available pages before exploring further.
- Case 1 – Basic: Sync three loyalty tags to OneSignal via API and send weekly point reminder emails and reward-unlock notifications. No purchase event tracking required.
- Case 2 – Advanced: Same tag sync as Case 1. Adds post-purchase points confirmation emails, a multi-step lapsed customer winback series and a webhook to confirm redemptions with your loyalty backend.
Overview
Your loyalty system is the source of truth for points and rewards. OneSignal stores a copy of each customer’s loyalty state as data tags and uses those tags to personalize and trigger messages automatically.- Your loyalty system updates OneSignal tags via the Update user API endpoint whenever a customer earns points, redeems a reward or crosses a threshold
- OneSignal segments update in real time as tag values change
- Journeys are triggered by segment entry or custom event, using Liquid to pull each customer’s points data into the message
- You track email opens, clicks and downstream purchases to measure ROI
Prerequisites
For both cases:- OneSignal app with email configured
- An external loyalty system that stores points balances, reward thresholds and redemption status
- API access to sync loyalty data to OneSignal as tags (see Update user API endpoint)
- A customer list with email addresses matched to OneSignal profiles via External ID
- Familiarity with Journeys overview concepts
- Tags
points_balance,points_to_next_rewardandrewards_availablesynced to each customer’s profile
- Tags
last_purchase_dateandlifetime_spendsynced to each customer’s profile - Custom events firing from your loyalty system when a purchase completes
- Journey webhooks enabled on your account (contact OneSignal sales for access)
Loyalty data setup
Your loyalty system syncs each customer’s state to OneSignal as data tags. The journey reads these tags to decide what to send and what to say.Tags to sync
| Tag | Type | Description | When to update |
|---|---|---|---|
points_balance | Number | Customer’s current point total | After every point-earning or redemption event |
points_to_next_reward | Number | Points needed to unlock the next reward | After every point-earning event |
rewards_available | Number | Number of rewards the customer can currently redeem | After points are earned or rewards are redeemed |
last_purchase_date | Date | Unix timestamp of the most recent purchase | After each purchase |
lifetime_spend | Number | Total spend in cents | After each purchase |
addTags method.
Case 1: Basic loyalty journey
Send weekly point reminders and reward-unlock notifications using three synced tags. No purchase event tracking required.Overview
Two journeys run in parallel for each enrolled customer:- Weekly points reminder: Re-enters every 7 days and sends a personalized email with the customer’s current balance and progress toward their next reward.
- Reward ready notification: Triggers when a customer newly qualifies for a reward and sends an email prompting redemption before it goes unused.
Journey 1: Weekly points reminder
Journey settings
Configure these settings on the Settings tab before building the steps. See Journey settings for full reference.| Setting | Value |
|---|---|
| Entry rules: Audience segment | points_balance exists AND has email subscription |
| Entry rules: Future additions only | Unchecked. All enrolled loyalty members enter when the journey launches. |
| Re-entry rules | Enabled. Allow re-entry after 7 days. Each customer exits after the email send, re-enters 7 days later and receives the next week’s reminder. |
| Exit rules | None. |
Required segments
| Segment name | Filters |
|---|---|
| Loyalty email subscribers | points_balance exists AND has email subscription |
Journey steps
Time Window
Tuesday through Thursday, 10 AM to 2 PM in the user’s timezone. This limits delivery to mid-week, mid-morning windows when retail loyalty emails tend to see higher open and click rates.
Email: Weekly points summary
Use Liquid syntax to pull each customer’s loyalty data into the email. Include the current balance, points needed for the next reward and a clear call to action to visit or purchase.Subject: “You have {{ points_balance }} points. Your next reward is {{ points_to_next_reward }} points away.”Body highlights:
- Current balance: {{ points_balance }} points
- Points to next reward: {{ points_to_next_reward }} to go
- Progress bar visual (built in your email template)
- CTA: “Order now to earn more points”
Journey 2: Reward ready notification
This journey fires once each time a customer newly qualifies for a reward so they know to redeem it before it goes unused.Journey settings
| Setting | Value |
|---|---|
| Entry rules: Audience segment | rewards_available > 0 |
| Entry rules: Future additions only | Checked. Only customers who newly enter this segment receive the notification. Customers who already qualify at launch are excluded permanently. Even if they leave the segment and re-enter later, they will not receive this notification. |
| Re-entry rules | Enabled. Allow re-entry after 30 days. This lets the journey fire again the next time a customer earns a new reward after redeeming a previous one. |
| Exit rules | None. |
Required segments
| Segment name | Filters |
|---|---|
| Has redeemable reward | rewards_available > 0 |
Journey steps
Email: Reward unlocked
Subject: “You’ve earned a reward. Ready to redeem?”Body highlights:
- Rewards available: {{ rewards_available }}
- What the reward covers (pulled from a tag or hardcoded based on your program’s structure)
- CTA: “Redeem now”
- Secondary message: current balance and points to the next reward threshold
Wait: 3 days
Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
Yes/No Branch
Condition: user is in Has redeemable reward segment.
- Yes (reward still unused): Continue to the reminder email below.
- No (redeemed): Exit the journey. No reminder needed.
Success metrics to track
- Weekly email open rate and click-to-open rate
- Reward redemption rate within 7 days of the unlock notification
- Purchase frequency lift for customers in the journey vs. a holdout group
- Revenue per email sent
Best practices for Case 1
- Let Liquid do the personalization. A subject line that shows the customer’s point balance outperforms a generic “Check your rewards” subject. Every customer sees their own number, which makes the email feel relevant rather than bulk.
- Keep the weekly email focused. One primary message: here is your balance and here is how close you are to a reward. Avoid adding promotions or unrelated offers. The loyalty summary email performs better when it stays on topic.
- Sync tags frequently. The weekly email is only as accurate as the tag data behind it. Sync
points_balanceandpoints_to_next_rewardafter every point-earning event so the email reflects the customer’s real state at send time.
Case 2: Advanced loyalty journey
Same two journeys as Case 1, plus a post-purchase points confirmation email and a lapsed customer winback series.Overview
Case 2 adds two journeys to the two in Case 1:- Post-purchase follow-up: Triggered by a
purchase_completeevent. Sends a points credit confirmation shortly after the transaction and shows the customer how close they are to their next reward. - Lapsed customer winback: Triggered when
last_purchase_dateindicates inactivity. Sends a two-step email series with escalating incentives to bring the customer back.
Required data
Additional tags for Case 2
Tagslast_purchase_date and lifetime_spend are required in addition to the Case 1 tags. See Loyalty data setup for sync instructions.
Events to track
| Event | Description | How to trigger |
|---|---|---|
purchase_complete | Customer completes a purchase | Fire from your loyalty system backend with amount and points_earned as properties |
Required segments
In addition to Case 1 segments, create:| Segment name | Filters |
|---|---|
| Lapsed 30 days | last_purchase_date > 29 days ago |
| Lapsed 60 days | last_purchase_date > 59 days ago |
| Purchased recently | last_purchase_date < 30 days ago |
Journey 2 update: Add a Webhook step
In Case 2, add a Webhook step to Journey 2 immediately after the “Email: Reward unlocked” step. This notifies your loyalty backend each time a reward-unlock notification sends so it can track delivery and flag unredeemed rewards.Journey 3: Post-purchase points confirmation
Journey settings
| Setting | Value |
|---|---|
| Entry trigger | Custom event: purchase_complete |
| Re-entry rules | Automatic. Custom event journeys always allow re-entry. Each purchase_complete event triggers a new run through this journey. |
| Exit rules | None. |
Journey steps
Wait: 15 minutes
Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
Journey 4: Lapsed customer winback
Journey settings
| Setting | Value |
|---|---|
| Entry rules: Audience segment | Lapsed 30 days |
| Entry rules: Future additions only | Checked. Only customers who newly cross 30 days inactive enter. |
| Re-entry rules | Not enabled. A customer receives one winback series per lapse period. |
| Exit rules | Exit when user enters Purchased recently segment. This removes them from the series if they make a purchase before the 60-day escalation sends. |
Journey steps
Email: We miss you
Subject: “You have {{ points_balance }} points waiting. Come back and use them.”Body highlights:
- Points balance and how close the customer is to a reward
- A reminder of what their rewards can get them
- CTA: “Order now”
Wait: 14 days
Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
Yes/No Branch
Condition: user is in Lapsed 60 days segment.
- No: Exit the journey. The customer hasn’t reached 60 days inactive and doesn’t need the escalation email. Any customer who made a purchase during the journey would have already exited via the exit rule.
- Yes (still lapsed): Continue to the escalation email below.
Email: Escalation with incentive
Subject: “Still {{ points_balance }} points waiting. Here’s a reason to come back.”Body highlights:
- Points balance (still theirs, not expiring)
- A limited time bonus offer or discount to incentivize the first purchase back
- Clear expiry on the offer to create urgency
- CTA: “Claim your offer”
Success metrics to track
In addition to Case 1 metrics:- Post-purchase email open rate and influence on next-visit return rate
- Winback email conversion rate at 30-day and 60-day lapse
- Revenue recovered from lapsed customers per 1,000 emails sent
- Redemption webhook delivery rate (confirms your backend is receiving events)
Best practices for Case 2
- Send the post-purchase email fast. A points credit confirmation sent within minutes of a transaction reinforces the earning behavior and shows the customer their loyalty is being tracked. The 15-minute Wait accounts for tag sync time while keeping the email timely.
- Make the winback offer specific. A generic “we miss you” email without an offer underperforms one with a concrete, time-limited incentive. Tie the offer value to the customer’s points balance or spend history so high-value lapsed customers get a stronger reason to return.
- Exit customers who return mid-series. The exit rule on the winback journey removes customers who make a purchase before the 60-day escalation. Avoid sending a discount to someone who already returned without one.
Case 1 vs. Case 2 at a glance
| Case 1: Basic | Case 2: Advanced | |
|---|---|---|
| Tags required | 3 (points_balance, points_to_next_reward, rewards_available) | 5 (adds last_purchase_date, lifetime_spend) |
| Events required | None | purchase_complete |
| Journeys | 2 (weekly reminder, reward unlock) | 4 (adds post-purchase confirmation, lapsed winback) |
| Primary channel | ||
| Personalization | Points balance, reward proximity | All Case 1 fields, plus points earned per transaction |
| Winback | None | Two-step email series at 30 and 60 days inactive |
| Backend sync | One way. Loyalty system writes tags to OneSignal. | Adds webhook step in Journey 2 to notify your loyalty backend when a reward-unlock notification sends |
| Best for | Teams proving loyalty email ROI for the first time | Teams ready to connect messaging directly to purchase behavior |
Getting started
Start with Case 1. Set up the three core tags, build the two journeys and let them run for four weeks before evaluating. The weekly reminder and reward-unlock notification together give you enough data to measure whether loyalty messaging is driving incremental purchases. Once you have baseline data, add Case 2 journeys one at a time. The post-purchase points confirmation is the highest-ROI addition since it arrives immediately after a transaction and reinforces the earning behavior at exactly the right moment.Industry-specific versions
This tutorial covers a general loyalty program structure. For a version tailored to mobile gaming, including in-app tier celebrations, session-based entry and push as the primary channel, see the mobile gaming edition.Loyalty Journey: Mobile Gaming
Reward continued play, move players through loyalty tiers and turn retained players into advocates.
Track performance
Goals
Set a target metric on your journey and track progress in real time on the delivery report.