Engagement
Rewards
Issue, track, and redeem loyalty points tied to location events.
Overview
The Rewards module lets you programmatically issue points to users based on location triggers, track balances, and handle redemptions.
Check a balance
typescript
1import { createOxinion } from 'oxinion';
2
3const oxinion = createOxinion({ apiKey: 'pk_...' });
4
5const { data, error } = await oxinion.rewards.getBalance({ userId: 'user-123' });
6
7if (data) {
8 console.log('Balance:', data.balance); // number
9}
Issue points
typescript
1// Requires sk_ key (server-side only)
2const oxinion = createOxinion({ apiKey: process.env.OXINION_API_KEY! }); // sk_...
3
4await oxinion.rewards.issue({
5 userId: 'user-123',
6 points: 50,
7 reason: 'geofence.entered:zone_downtown',
8}); // returns void
Redeem a reward
typescript
1await oxinion.rewards.redeem({
2 userId: 'user-123',
3 rewardId: 'reward_abc',
4}); // returns void
Listen for reward events
typescript
1oxinion.rewards.listen('issued', (event) => {
2 // RewardsIssuedEvent: { userId, points, balance, reason, timestamp }
3 console.log(`+${event.points} pts → balance: ${event.balance}`);
4});
5
6oxinion.rewards.listen('redeemed', (event) => {
7 // RewardsRedeemedEvent: { userId, rewardId, pointsSpent, balance, timestamp }
8 console.log(`Redeemed ${event.rewardId}, spent ${event.pointsSpent} pts`);
9});
10
11oxinion.rewards.listen('tier_changed', (event) => {
12 console.log(`New tier: ${event.tier.name}`);
13});
Methods
rewards.getBalance({ userId })
Returns { balance: number }.
rewards.issue({ userId, points, reason, metadata? })
Issue points to a user. Requires sk_ key. Returns void.
rewards.redeem({ userId, rewardId })
Mark a reward as redeemed. Returns void.
rewards.listRewards()
List available rewards with their pointCost.
rewards.tiers.getCurrent({ userId })
Get the user's current tier and progress to the next.
rewards.tiers.list()
List all configured tiers.
rewards.listen(event, handler)
Events: issued | redeemed | tier_changed.