Shopper insights

Because VINR links every payment to a shopperReference regardless of which channel it originates from, you can analyse purchase behaviour across the full customer journey — not just within one channel. A shopper who browses online, buys in store, then requests a refund via pay-by-link appears as a single identity in your data, giving you a coherent picture of value, preferences, and conversion that per-channel analytics cannot provide.

What data is availableAskCopy

VINR's unified transaction data exposes the following dimensions per shopper:

• Per-shopper spend by channel — lifetime and period spend broken down by online, in_person, and pay_by_link.
• Channel preference over time — how the mix of channels a shopper uses shifts across quarters or seasons.
• First-channel attribution — which channel the shopper first transacted on, so you know where acquisition actually happened.
• Cross-channel conversion — shoppers who interacted on one channel (e.g. browsed via an online session) and completed a purchase on another (e.g. in store).
• Return rates by channel — refund and return frequency broken down by the originating channel.
• Average order value by channel — whether a shopper spends more in store, online, or via link.

All dimensions are available from the date the shopperReference was first used on your account.

Query shopper historyAskCopy

vinr.payments.list accepts a shopperReference alongside date filters and returns every payment for that shopper across all channels. Each payment object includes a channel field ('online' | 'in_person' | 'pay_by_link'), amount, currency, and createdAt.

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

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

const payments = await vinr.payments.list({
  shopperReference: 'shopper_8A2KX',
  fromDate: '2025-01-01',
  toDate: '2026-01-01',
});

type ChannelKey = 'online' | 'in_person' | 'pay_by_link';

const spendByChannel = payments.data.reduce<Record<ChannelKey, number>>(
  (acc, payment) => {
    const channel = payment.channel as ChannelKey;
    acc[channel] = (acc[channel] ?? 0) + payment.amount;
    return acc;
  },
  { online: 0, in_person: 0, pay_by_link: 0 },
);

console.log(spendByChannel);

The payments.data array is ordered by createdAt descending. Paginate using the cursor field on the response if the shopper has a large transaction history.

Payment object field reference

Dashboard reportsAskCopy

The VINR Dashboard exposes pre-built shopper analytics under Reporting → Shoppers:

• Top spenders by channel — ranked list filterable by date range and channel.
• Cohort analysis — groups shoppers by their first-purchase month; tracks how many transact again in subsequent months and on which channels.
• Channel mix chart — stacked bar chart showing what percentage of revenue each channel contributed per week or month.

All views support CSV export. Use the export to feed downstream tools such as your CRM, marketing platform, or BI suite.

SegmentationAskCopy

The payments list endpoint accepts several filter parameters that let you target specific shopper segments.

const inStoreOnly = await vinr.payments.list({
  channel: 'in_person',
  fromDate: '2025-01-01',
});

const shopperEmails = inStoreOnly.data
  .filter((p) => p.shopperEmail)
  .map((p) => p.shopperEmail as string);

const payments = await vinr.payments.list({ fromDate: '2024-01-01' });

const spendByRef = new Map<string, number>();
for (const p of payments.data) {
  spendByRef.set(
    p.shopperReference,
    (spendByRef.get(p.shopperReference) ?? 0) + p.amount,
  );
}

const highValue = [...spendByRef.entries()]
  .filter(([, total]) => total >= 100000)
  .map(([ref]) => ref);

const locationPayments = await vinr.payments.list({
  channel: 'in_person',
  'metadata.locationId': 'loc_MANHATTAN_5TH',
  fromDate: '2025-06-01',
});

Once you have a list of shopperReference values or shopperEmail addresses, export them and upload to your email platform to run targeted campaigns — for example, inviting high-value in-store shoppers to your online loyalty programme.

AttributionAskCopy

VINR supports both first-touch and last-touch attribution using fields on the payment object and its metadata.

const payment = await vinr.payments.create({
  amount: 4900,
  currency: 'GBP',
  shopperReference: 'shopper_8A2KX',
  metadata: {
    acquisitionChannel: 'paid_search',
    campaignId: 'gs_spring_2026',
  },
});

const history = await vinr.payments.list({
  shopperReference: 'shopper_8A2KX',
  fromDate: '2024-01-01',
});

const sorted = history.data.sort(
  (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
);

const firstTouch = sorted.at(0)?.metadata?.acquisitionChannel;
const lastTouch  = sorted.at(-1)?.channel;

console.log({ firstTouch, lastTouch });

If your OMS does not set acquisitionChannel, you can backfill it on existing payments using vinr.payments.update({ id, metadata: { acquisitionChannel: '…' } }). Backfilling does not affect the settled payment; it only updates the metadata record.

Next stepsAskCopy