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",
  key: "baseball-cap-2025", // identifier for the reward
  points: 10,
  targetPointSystemId: pointSystemId,
  type: RewardOfferType.REDEMPTION_OFFCHAIN,
});

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

Optionally, the maximum number of claims can be specified per user/reward offer. Below, the reward can be claimed up to 100 times and once per user.

const reward = await stack.createRewardOffer({
  name: "T shirt",
  key: "t-shirt-2025",
  points: 10,
  targetPointSystemId: pointSystemId,
  type: RewardOfferType.REDEMPTION_OFFCHAIN,
  metadata: {
    maxClaims: 100,
    maxClaimsPerUser: 1,
  }
});

Params

Name	Description
name	The name of the reward
key (optional)	Key for identifying 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
metadata (optional)	Reward offer claim parameters

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'
  }
})

Claiming a reward by key

Alternatively, use the reward key instead of uuid to specify a reward offer.

const claim = await stack.claimRewardByKey("baseball-cap-2025", {
  address: account,
  points: 10,
});

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

Update reward name

const reward = await stack.updateRewardOffer({
  name: "New T shirt",
  rewardOfferUuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc'
});

Delete reward offer

const reward = await stack.deleteRewardOffer({
  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'
//   }
// ]

Query for reward offers

const rewards = await stack.getRewardOffers({
  query: {
    where: {
      uuid: 'ac767a23-40f9-4c6e-94ee-15129ef42dfc'
    }
  }
});

// [
//   {
//     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'
//   }
// ]

Alternatively, querying by key:

const claims = await stack.getRewardClaims({
  query: stack.rewardClaimsQuery()
    .where({
      key: 'baseball-cap-2025',
    })
    .limit(20)
    .offset(0)
    .build()
});

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
//   }