# Present a user’s 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.

{% hint style="info" %}
This guide assumes you are calling APIs with the **user’s own token**, not an admin token.
{% endhint %}

For conceptual background, see:

* [User wallet](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/users/user-wallet)
* [Benefits](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/benefits#benefit-lifecycle)
* [Reward types](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types)

***

## Implementation Steps

{% stepper %}
{% step %}

### Retrieve wallet data

Use the [Retrieve Wallet API](https://docs.whitelabel-loyalty.com/rewards.html#users-active-user-wallet-get).

This returns:

* Current points balance
* Current tier
* Lifetime points earned
* Vouchers (both unredeemed and redeemed but not yet burned)

```bash
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"
```

{% endstep %}

{% step %}

### Retrieve points liability predictions

Optionally, if you are using [Points liability](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/points/points-liability) features like [Points earn, spend & balance caps](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/points/points-earn-spend-and-balance-caps) or [Points expiry](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/points/points-expiry)[,](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/points/points-expiry) you can show predictions for the caps to user’s wallet points using the [Wallet Predictions API](https://docs.whitelabel-loyalty.com/rewards#users-active-user-wallet-predictions).

This returns:

* `pointsSpendPrediction`
* `pointsEarnPrediction`
* `pointsExpiryPrediction`

```bash
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"
```

{% endstep %}

{% step %}

### Retrieve benefits

Use the [List All Benefits API](https://docs.whitelabel-loyalty.com/rewards.html#benefits-benefits-collection).

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

{% hint style="info" %}
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](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/benefits#flow-by-benefit-type).
{% endhint %}

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

{% endstep %}

{% step %}

### Retrieve earned badges

Use the [Earned Badges API](https://docs.whitelabel-loyalty.com/rewards.html#badges-earned-badges).

This returns all badges the user has earned.

```bash
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>" \
```

{% endstep %}
{% endstepper %}

***

## 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](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/points/points-liability) features.
* **Benefits & Vouchers:** from Benefits API.
* **Badges:** from Earned Badges API.

***

## Example: Combining in Node.js

{% code expandable="true" %}

```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);
```

{% endcode %}

***

## Next Steps

* Learn more about [User wallet](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/users/user-wallet)
* Explore the [Benefits](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/benefits#benefit-lifecycle)
* Review the [Reward types](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kbase.whitelabel-loyalty.com/developer/guides/present-a-users-loyalty-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.