Rewards

Stack SDK supports creating offchain rewards and redeeming points.

For onchain rewards, use the Rewards dashboard.

Creating a reward offer

const reward = await stack.createRewardOffer({
  name: "Baseball cap",
  points: 10,
  targetPointSystemId: pointSystemId,
  type: RewardOfferType.REDEMPTION_OFFCHAIN,
});

// {
//   uuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
//   name: 'test reward',
//   type: 'REDEMPTION_OFFCHAIN',
//   points: 1,
//   metadata: {},
//   status: 'ACTIVE',
//   createdAt: '2024-08-14T20:03:32.273Z',
//   updatedAt: '2024-08-14T20:03:32.273Z'
// }

Params

Name	Description
name	The name of the reward
points	Amount of points a user spends to redeem (use 0 if no points needed)
targetPointSystemId	The point system ID for this reward
type	The type of reward offer

Claiming a reward

By claiming a reward for a user, the user's points will be subtracted. The request will error if the user does not have sufficient balance.

const account = '0xA78D472a4F8060e67438F515480Ce8080Bd7FF71';
const claim = await stack.claimReward(reward.uuid, {
  address: account,
  points: 10,
});

// {
//   address: '0xA78D472a4F8060e67438F515480Ce8080Bd7FF71',
//   rewardOfferUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
//   claimedAt: '2024-08-14T20:03:33.794Z'
// }

When a reward is claimed, a redeem event will be tracked to the point system if the reward costs more than 0 points. Using the example, the tracked event is equivalent to:

stack.track("redeem", {
  account: '0xA78D472a4F8060e67438F515480Ce8080Bd7FF71',
  points: -10,
  metadata: {
    rewardOfferUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc'
  }
})

Get reward offers

List reward offers

const rewards = await stack.getRewardOffers();

// Returns a list of reward offers

// [
//   {
//     uuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
//     name: 'test reward',
//     type: 'REDEMPTION_OFFCHAIN',
//     points: 1,
//     metadata: {},
//     status: 'ACTIVE',
//     createdAt: '2024-08-14T20:03:32.273Z',
//     updatedAt: '2024-08-14T20:03:32.273Z'
//   }
// ]

Get reward claims

List reward claims for a particular reward offer.

const claims = await stack.getRewardClaims({
  query: stack.rewardClaimsQuery()
    .where({
      offerUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
    })
    .limit(20)
    .offset(0)
    .build()
});

// Returns a list of claims

// [
//   {
//     address: '0xA78D472a4F8060e67438F515480Ce8080Bd7FF71',
//     rewardOfferUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
//     claimedAt: '2024-08-14T20:03:33.794Z'
//   }
// ]

Get reward metrics

Get reward claim metrics given a RewardClaimsQuery

const claims = await stack.getRewardClaims({
  query: stack.rewardClaimsQuery()
    .where({
      offerUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc',
    })
    .build()
});

// Returns totalClaims

//   {
//     totalClaims: 1
//   }