Basic Usage

Award points for a purchase

One call registers the order and credits the points. Identify the customer by user_email or user_id; order_id is your own reference and is required.

const transaction = await sdk.createTransaction({
  user_email: 'customer@example.com',
  order_id: 'ORD-2024-001',
  order_total: 25.50,
  currency: 'EUR',
  shop_id: 1,
  description: 'Online purchase',
});

Points come from order_total and the partner's rules. Override them with points:

await sdk.createTransaction({
  user_email: 'customer@example.com',
  order_id: 'ORD-2024-002',
  order_total: 25.50,
  points: 500,          // award exactly 500 instead of calculating
});

If the customer also spent points on the order, report that in the same call:

await sdk.createTransaction({
  user_email: 'customer@example.com',
  order_id: 'ORD-2024-003',
  order_total: 45.00,
  points_redeemed: 500,
  points_discount_amount: 5.00,
});

Reverse a transaction

Use the same order_id with type: 'cancellation' or 'refund'. Earned points are taken back and redeemed points returned.

await sdk.createTransaction({
  user_email: 'customer@example.com',
  order_id: 'ORD-2024-001',
  type: 'refund',
  order_total: 25.50,
});

Transaction history

const history = await sdk.getTransactions({ page: 1, per_page: 20 });

Note

To hold points while a customer is still on the checkout page, call POST /{locale}/shop/points/reserve and points/release directly — the SDKs do not wrap them yet.

Loyalty cards

// Look up one card by user ID, card ID or card number
const card = await sdk.getLoyaltyCardInfo({ user_id: userId });

// Points balance
const balance = await sdk.getPointsBalance({ card_id: card.id });

// The partner's card designs — artwork and points rules, not customers' cards
const designs = await sdk.getLoyaltyCards({ per_page: 50 });

Coupons

Verify before you discount, then redeem after the sale goes through.

const check = await sdk.verifyCoupon('SUMMER10', shopId);
const discount = await sdk.calculateCouponDiscount('SUMMER10', 50.00);

await sdk.setCouponPending(check.coupon.id, shopId);   // hold during checkout
await sdk.redeemCoupon(check.coupon.id, shopId);       // final
// or, if the sale falls through:
await sdk.cancelCouponPending(check.coupon.id, shopId);

A customer's own coupons:

const coupons = await sdk.getCardCoupons(shopId, cardId);

Games and stamp cards

const games = await sdk.listShopGames(shopId);
const active = await sdk.getCardGames(cardId, shopId);

await sdk.addStamps(gameId, cardId, shopId, 1);
const progress = await sdk.getGameProgress(gameId, cardId);

When a stamp card fills up, the reward is issued automatically. completeStampCard and restartGame let you close and restart a round by hand.

Shops and offers

const shops = await sdk.getShops();          // shop_id values for the calls above
const offers = await sdk.getOffers();

Errors

The SDK throws LoyaltySDKError. statusCode is the HTTP status, code is the API's numeric application code (or a string like NETWORK_ERROR when the request never reached the API).

import { LoyaltySDKError } from '@loyaltylt/sdk';

try {
  await sdk.createTransaction({ order_id: 'ORD-1', user_email: 'nobody@example.com' });
} catch (error) {
  if (error instanceof LoyaltySDKError) {
    if (error.statusCode === 422) console.error('Invalid request:', error.message);
    else if (error.statusCode === 401) console.error('Check your API credentials');
    else console.error(error.code, error.message);
  }
}

429 and 5xx are retried automatically — see the retries option.

Pure helpers for showing "you will earn N points" before you call the API: calculatePointsFromAmount, calculateAmountFromPoints, calculateFinalAmount, calculateMaxRedeemablePoints, validatePointsRedemption. All take the partner's points rules as their second argument.

QR login

Sign a customer in from a screen

QR card scan

Identify a customer at the POS

Examples

A full checkout and a full till