Present a user’s loyalty status

Learn how to integrate Wallet, Benefits, Tiers, and Badges APIs together in your application to show a logged-in user their complete loyalty status.

Overview

Presenting a logged-in user with their loyalty status is a common use case when integrating WLL APIs. In WLL, loyalty status spans several concepts: Wallet, Benefits, Tiers, and Badges.

This guide shows how to combine these APIs to retrieve wallet data (including tiers), benefits (including vouchers) and badges, and display them together as a complete picture of the user’s loyalty status.

This guide assumes you are calling APIs with the user’s own token, not an admin token.

For conceptual background, see:

• User wallet

• Benefit lifecycle

• Reward types

---

Implementation Steps

1

Retrieve wallet data

Use the Retrieve Wallet API.

This returns:

• Current points balance

• Current tier

• Lifetime points earned

• Vouchers (both unredeemed and redeemed but not yet burned)

curl -X GET "https://api.staging.rewards.wlloyalty.net/v1/users/me/wallet" \
  -H "Authorization: Bearer <user_token>" \
  -H "X-Api-Key: <your_tenant_api_key>" \
  -H "Content-Type: application/json"

2

Retrieve points liability predictions

Optionally, if you are using Points liability features like Points earn, spend & balance caps or Points expiry, you can show predictions for the caps to user’s wallet points using the Wallet Predictions API.

This returns:

• pointsSpendPrediction

• pointsEarnPrediction

• pointsExpiryPrediction

curl -X GET "https://api.staging.rewards.wlloyalty.net/v1/users/me/wallet/predictions" \
  -H "Authorization: Bearer <user_token>" \
  -H "X-Api-Key: <your_tenant_api_key>" \
  -H "Content-Type: application/json"

3

Retrieve benefits

Use the List All Benefits API.

This returns all benefits linked to the user (vouchers + other reward types). You can filter to only unredeemed benefits with ?redeemable=true.

Vouchers are a special type of benefit, so benefits may overlap with vouchers returned by the Wallet API. For gift cards specifically, see Benefits flow.

curl -X GET "https://api.staging.rewards.wlloyalty.net/v1/benefits" \
  -H "Authorization: Bearer <user_token>" \
  -H "X-Api-Key: <your_tenant_api_key>" \

4

Retrieve earned badges

Use the Earned Badges API.

This returns all badges the user has earned.

curl -X GET "https://api.staging.rewards.wlloyalty.net/v1/badges/earned" \
  -H "Authorization: Bearer <user_token>" \
  -H "X-Api-Key: <your_tenant_api_key>" \

---

Putting it together

With the above APIs, you can now present:

• Points & Tier: from Wallet API.

• Predictions: optional, from Wallet Predictions API. Useful when using Points liability features.

• Benefits & Vouchers: from Benefits API.

• Badges: from Earned Badges API.

---

Example: Combining in Node.js

import axios from "axios";

const USER_TOKEN = "<user_token>";
const client = axios.create({
  baseURL: "https://api.staging.rewards.wlloyalty.net/v1",
  headers: { Authorization: `Bearer ${USER_TOKEN}` }
});

async function getUserStatus() {
  const [wallet, benefits, badges, predictions] = await Promise.all([
    client.get("/users/me/wallet"),
    client.get("/benefits"),
    client.get("/badges/earned")
    client.get("/users/me/wallet/predictions")
  ]);

  return {
    points: wallet.data.pointsBalance,
    tier: wallet.data.tier,
    lifetimePoints: wallet.data.lifetimeEarn,
    vouchers: wallet.data.vouchers,
    benefits: benefits.data,
    badges: badges.data
    walletPredictions: predictions.data
  };
}

getUserStatus().then(console.log).catch(console.error);

---

Next Steps

• Learn more about User wallet

• Explore the Benefit lifecycle

• Review the Reward types