Skip to main content

Points & Tiers

The useLoyalty hook fetches the customer’s loyalty account and transaction history.

Usage

import { useLoyalty } from 'react-native-stackfront-sdk';

function LoyaltyStatus({ customerId }: { customerId: string }) {
  const { account, transactions, loading } = useLoyalty(customerId);

  if (loading) return <Loading />;

  return (
    <View>
      <Text>Points: {account?.pointsBalance ?? 0}</Text>
      <Text>Lifetime Points: {account?.lifetimePoints ?? 0}</Text>
      <Text>Current Tier: {account?.currentTier?.name ?? 'Bronze'}</Text>
      <Text>Progress to next tier: {account?.progressPercent ?? 0}%</Text>

      <Text>Recent Transactions:</Text>
      {transactions.map((tx) => (
        <TransactionRow key={tx.id} transaction={tx} />
      ))}
    </View>
  );
}

Hook API

function useLoyalty(customerId: string, customerEmail?: string): {
  account: LoyaltyAccountSdkResponse | null;
  transactions: LoyaltyTransactionResponse[];
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
  redeem: (pointsToRedeem: number, orderTotal: number) => Promise<RedeemPointsResponse>;
}

Account Shape

{
  pointsBalance: number;
  lifetimePoints: number;
  currentTier: {
    name: string;
    minPoints: number;
    maxPoints: number;
    benefits: string[];
  };
  nextTier: {
    name: string;
    minPoints: number;
    benefits: string[];
  } | null;
  progressPercent: number;
}

Transaction Shape

{
  id: string;
  type: 'earned' | 'redeemed' | 'expired' | 'adjusted';
  points: number;
  description: string;
  createdAt: string;
  referenceType: string | null;
  referenceId: string | null;
}

Service API

const { loyalty } = useStackfront();

const account = await loyalty.getAccount('customer-id', 'email@example.com');
const txs = await loyalty.getTransactions('customer-id', 1, 20);