How engagement works
The objects and flow behind loyalty and rewards on VINR.
Engagement composes members, a loyalty currency, earning rules, and rewards into programs that react to events — most often a payment. Understand the object graph and the event loop, and every feature (tiers, campaigns, referrals, store credit) becomes a variation on the same pattern.
Core objectsAsk
| Object | What it answers |
|---|---|
program | The loyalty program — its currency, rules, and tiers. |
loyalty_account | Who — a member, linked to a customer. |
earning_rule | How members earn points from events. |
points_transaction | A single award, deduction, or expiry. |
reward / redemption | What points buy, and a member spending them. |
// Enroll a member and link them to an existing customer.
const member = await vinr.loyalty.accounts.create({
program: 'prog_default',
customer: 'cust_abc123',
}); // "loy_..."Events that drive engagementAsk
Engagement subscribes to events from across VINR. The most important is payment.completed, but rules can react to many triggers:
| Trigger | Typical rule |
|---|---|
payment.completed | Award N points per €1 spent. |
loyalty.account.created | Welcome bonus. |
subscription.created | Bonus for going annual. |
referral.converted | Reward both referrer and referee. |
From purchase to points to rewardAsk
A payment completes
The customer pays. If the payment is linked to a member (via customer or metadata), Engagement evaluates earning rules.
Points are awarded
A matching earning rule creates a points_transaction, increasing the member's balance and emitting loyalty.points.earned.
The member redeems
The member spends points on a reward — often a discount applied at checkout. This deducts points and issues the reward.
Refunds claw back
If the original purchase is refunded, Engagement reverses the points it awarded, keeping balances honest. See Linking payments & loyalty.
Where Payments & Billing fitAsk
Engagement sits downstream of Payments and Billing — it never collects money, it reacts to it. A one-time payment or a subscription renewal both emit events that can earn points, qualify a member for a tier, or progress a campaign.
The single most important integration step is identifying the member on each payment so purchases earn and redemptions discount. Get that right and the rest is configuration.
Where to go nextAsk
Loyalty accounts
Enroll and manage members.
Linking payments & loyalty
The core integration.
Launch a loyalty program
A runnable end-to-end guide.
Last updated on
