Cross-channel loyalty

Loyalty is most powerful when it works the same way whether the customer buys online, taps at the terminal, or orders over the phone. VINR ties payment events to the engagement stack via shopperReference so points accrue and redeem across channels automatically — there is no separate loyalty middleware to maintain and no risk of a customer's in-store balance being invisible at your web checkout. See Engagement for the full loyalty feature set including tier configuration, reward catalogues, and expiry rules.

How it worksAskCopy

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

export async function handlePaymentCompleted(event: WebhookEvent) {
  const { shopperReference, amount, currency, id: paymentId } = event.data;

  if (!shopperReference) return;

  await vinr.engagement.loyalty.credit({
    shopperReference,
    points: Math.floor(amount / 100),
    currency,
    sourceType: 'payment',
    sourceId: paymentId,
    metadata: {
      channel: event.data.metadata?.channel ?? 'unknown',
    },
  });
}

Earning points at the terminalAskCopy

Pass shopperReference on every terminal payment request. VINR links the terminal transaction to the shopper profile in the same way as an online payment, and the same payment.completed webhook fires with the reference included.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const terminalPayment = await vinr.terminal.payments.create({
  terminalId: 'term_london_01',
  amount: 4200,
  currency: 'GBP',
  shopperReference: 'cust_abc123',
  receiptData: {
    pointsEarned: 42,
    loyaltyBalanceAfter: 1380,
  },
});

receiptData.pointsEarned and receiptData.loyaltyBalanceAfter surface on the printed and digital receipts so staff can read the points earned aloud and the customer sees confirmation on their copy. Retrieve the current balance before creating the payment to populate loyaltyBalanceAfter accurately.

For the full terminal payment reference see Shopper recognition.

Redeeming in storeAskCopy

When a customer mentions their loyalty balance at the counter, staff retrieve it before creating the payment. The redemption value is applied as a discount; any remaining basket value is charged to the customer's card.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const balance = await vinr.engagement.loyalty.getBalance({
  shopperReference: 'cust_abc123',
});

const redeemPoints = 500;
const pointValue = balance.pointValueMinorUnit * redeemPoints;
const remainingAmount = Math.max(0, 6000 - pointValue);

await vinr.engagement.loyalty.redeem({
  shopperReference: 'cust_abc123',
  points: redeemPoints,
  sourceType: 'payment',
  metadata: { channel: 'in_store', staffId: 'staff_jsmith' },
});

const payment = await vinr.terminal.payments.create({
  terminalId: 'term_london_01',
  amount: remainingAmount,
  currency: 'GBP',
  shopperReference: 'cust_abc123',
  metadata: {
    loyaltyRedemption: true,
    pointsRedeemed: redeemPoints,
    pointsValueMinorUnit: pointValue,
  },
});

Redemption fieldsAskCopy

Redemption via terminal promptAskCopy

Configure a terminal input prompt to collect the customer's loyalty identifier — their account number, email address, or phone number — without staff manually looking it up. VINR maps the input to a shopperReference and surfaces the balance for staff to confirm before redemption.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const session = await vinr.terminal.sessions.create({
  terminalId: 'term_london_01',
  prompts: [
    {
      id: 'loyalty_lookup',
      type: 'text_input',
      label: 'Loyalty number or email',
      optional: true,
      keyboardType: 'email_address',
    },
  ],
});

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

export async function handleSessionPromptResponse(event: WebhookEvent) {
  const loyaltyInput = event.data.promptResponses?.loyalty_lookup;
  if (!loyaltyInput) return;

  const shopperReference = await vinr.engagement.loyalty.resolveIdentifier({
    identifier: loyaltyInput,
  });

  const balance = await vinr.engagement.loyalty.getBalance({ shopperReference });

  await vinr.terminal.sessions.update(event.data.sessionId, {
    display: {
      message: `Balance: ${balance.points} points (worth ${balance.formattedValue})`,
      confirmAction: 'Redeem',
      dismissAction: 'Skip',
    },
  });
}

See Receipts and engagement for the full terminal prompts and display reference.

Cross-channel point expiryAskCopy

Points earned online and in store share the same ledger and the same expiry rules. There is no separate expiry clock per channel — a point earned at the terminal and a point earned at web checkout age at the same rate under the same policy.

Configure expiry windows, rolling or fixed, in Loyalty accounts.

Next stepsAskCopy