Launch a loyalty program

Create a program and currency, define earning rules, build rewards, and go live.

This guide stands up a working loyalty program end-to-end: define your currency, enroll members, award points on purchases, and let members redeem rewards. Runnable against the sandbox.

Overview Ask

purchase ──► earning rule ──► points awarded ──► member balance ──► redemption ──► reward

A program holds your currency and rules; members are loyalty accounts linked to customers; earning rules turn events into points; rewards are what points buy.

Design your program Ask

Decide three things before writing code:

Decision	Example
Earn rate	1 point per €1 spent
Reward value	100 points = €5 off
Expiry	Points expire 12 months after earning

Create the program & currency Ask

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const program = await vinr.loyalty.programs.create({
  name: 'VINR Rewards',
  currency: { name: 'points', expiryMonths: 12 },
});                                  // "prog_..."

Enroll a member by linking an existing customer:

const member = await vinr.loyalty.accounts.create({
  program: program.id,
  customer: 'cust_abc123',
});                                  // "loy_..."

Define earning rules Ask

Map the payment.completed event to points. VINR evaluates the rule whenever a linked payment completes.

await vinr.loyalty.earningRules.create({
  program: program.id,
  trigger: 'payment.completed',
  earn: { pointsPerCurrencyUnit: 1 },     // 1 point per €1
  multipliers: [
    { when: { tier: 'gold' }, factor: 2 }, // gold members earn double
  ],
});

For points to be awarded, the payment must be linked to the member. Pass the customer (or a member id in metadata) when you create the payment.

Build a rewards catalog Ask

Define what points buy. This reward applies a €5 discount for 100 points.

const reward = await vinr.loyalty.rewards.create({
  program: program.id,
  name: '€5 off',
  cost: 100,                              // points
  benefit: { type: 'discount', amount: 500, currency: 'EUR' },
});                                       // "rwd_..."

Redeem on the member's behalf — typically at checkout:

const redemption = await vinr.loyalty.redemptions.create({
  account: member.id,
  reward: reward.id,
});
// redemption.discountId → apply to the payment/checkout session

React to engagement events Ask

Event	Use it to
`loyalty.points.earned`	Notify the member, update your UI.
`loyalty.tier.changed`	Unlock perks, send a congrats email.
`loyalty.points.expired`	Prompt re-engagement.