Loyalwell documentation
Loyalwell shows a customer's loyalty points next to their Zendesk ticket and lets the agents you allow add or deduct points and issue rewards, with every change logged on the ticket. It works with LoyaltyLion, Yotpo Loyalty & Referrals and Smile.io. Questions: hello@greatwork.company (a person replies within one business day).
Before you install
- Smile.io: Smile offers its API on the Plus and Enterprise plans, for Shopify and BigCommerce stores. On other Smile plans there's no API key to paste.
- LoyaltyLion: any plan with Manage > API keys. Loyalwell uses API keys, not the older token and secret, which LoyaltyLion retires on 10 January 2027.
- Yotpo Loyalty & Referrals: the GUID and API key from the Loyalty admin settings.
Setting up
- Create a key in your loyalty platform (table below), named "Loyalwell for Zendesk".
- In Zendesk, install Loyalwell. In Loyalty platform type
loyaltylion,yotpoorsmile, paste the key into API key, and for Yotpo the GUID into Yotpo GUID. - Optional: a Program label (shown in notes and the program switcher) and the Zendesk brand ids that should open this program.
- Choose who may take actions, the switches, the point limits and your reasons (below).
Key permissions
| Platform | To read | To take actions |
|---|---|---|
| LoyaltyLion | read_customers | write_customers (add and remove points, claim rewards) |
| Smile.io | customer:read, points_transaction:read, reward_fulfillment:read, points_product:read, vip_tier:read | points_transaction:write, points_purchase:write |
| Yotpo | the GUID and API key (Yotpo keys have no scopes) | the same |
A read-only key works: agents see everything and an action answers with a clear message from the
platform. On Smile, a key without reward_fulfillment:read or vip_tier:read still shows points
and history, just without codes or tier names.
Several programs
Fill in Loyalty platform (program 2) (that turns it on), its key, label and brands, and the same for program 3. Programs can be on different platforms. A ticket opens the program listed for its brand, else the first program with no brand list, else program 1. When nothing maps the brand (for example on a user profile), Loyalwell looks in the other programs once and opens the first one where the customer has a record. Agents can switch programs at the top of the sidebar.
What agents see
- Points: the balance the customer can spend, pending points (LoyaltyLion), lifetime earned (Yotpo) or spent (LoyaltyLion), and the next expiry when the platform reports it.
- Status: member, guest or not enrolled, opted out, blocked or disabled; LoyaltyLion's At Risk, Win Back and Loyal segments.
- Tier: name, start and end dates, progress to the next tier and what keeps the current one, as each platform reports it. Yotpo: "360 more points for Infused". Smile: "640 of 1,000 toward Gold" (points or spend, as your VIP program counts it). LoyaltyLion reports the tier and its dates; its API does not include progress in the customer record, so none is shown.
- Customer: birthday, order count (Yotpo), referral link and who referred them (LoyaltyLion).
- Rewards and codes: each redeemed reward with its code, used or unused, and expiry. Unused codes have Add code to reply, which puts the code in your reply draft (nothing is sent until you send the reply).
- Points history: newest first: orders, referrals, adjustments, redemptions and expiries.
- Find: look up another email address in the current program.
Actions
| Action | What happens | Notes |
|---|---|---|
| Add points | The platform adds the points with your reason | The customer sees the reason in their points history. On Yotpo you choose whether it also changes lifetime points earned (which counts toward VIP tiers) |
| Deduct points | The platform removes the points with your reason | Never more than the balance; pending points can't be deducted until approved |
| Issue a reward | The platform redeems a reward it offers for the customer's points and returns its code | Fixed-cost rewards that come back as a code (discounts, free shipping, gift cards). Free-product rewards and variable "spend any amount" rewards stay in your platform |
Every action shows the balance now and after (or the reward's cost) and the reason the customer will
see, before anything is sent. Loyalwell re-reads the customer right before sending, so it acts on the
current balance. Each change is sent once; if the connection drops, Loyalwell re-reads the history
to see whether it went through instead of sending it again. Then it writes an internal note on the
ticket and adds a tag: loyalwell_points_added, loyalwell_points_deducted or
loyalwell_reward_issued. On Smile, the transaction also carries a merchant-only note with the
Zendesk ticket number.
Tier changes
None of the three platforms lets an app set a customer's tier, so Loyalwell doesn't offer it. Tiers move with your program rules; on Yotpo, adding points that count toward lifetime earned moves VIP progress.
Settings
| Setting | Default | What it does |
|---|---|---|
| Who may take actions | agent | Comma separated: agent (everyone), admin, custom role ids, group:<id>. Everyone else sees the sidebar read-only |
| Allow adding points, deducting points, issuing rewards | on | Turn each action off for everyone |
| Most points per action | 500 | For agents with no role limit. Admins have no limit. 0 means no limit |
| Point limits by role | empty | One per line, for example agent 200, group:360001234567 2000, 360009876543 0. The most generous matching line applies; 0 means no limit. A line for admin limits admins too |
| Reasons the customer sees | standard list | One per line; agents can always type their own |
Limits
- Loyalwell doesn't change tiers, birthdays, enrollment, blocked status or program settings, and doesn't create customers.
- The history shows the latest 50 entries (LoyaltyLion, Smile) or what Yotpo returns; older entries stay in your platform.
- LoyaltyLion lists redeemed rewards from the same history, so very old codes may not show.
- Codes from Yotpo's history are read from the history entry's status, where Yotpo puts them.
Privacy
Your keys are Zendesk secure settings: they never reach agents' browsers, and Zendesk only sends them to your platform's API. Loyalwell has no server, keeps no copies, has no export, sends nothing to Great Work and uses no AI. Full policy: https://greatwork.company/apps/loyalwell/privacy.
Plans
Standard: $9 per agent per month, every feature, 14-day trial with a card. Billed by Zendesk.
Uninstall
Uninstalling deletes the stored keys. Delete the keys in your loyalty platform too. Notes and tags already on tickets stay.