Skip to main content
eligibility returns everything the app needs to gate a member’s experience in a single call: their tier and their wallet. It is a convenient first call when a screen loads, before listing offers or redeeming.
These are member-mode calls: they use the member token, not the Org-API-Key. See Authentication. Whether you read sandbox or live data is selected by the key the token was minted from - see Environments.

Get eligibility

eligibility(externalUserID?) calls GET /v1/eligibility and returns a MemberEligibility. The snippet below reads the tier and balance, then fetches the full wallet:
import { initialize } from "@expys/sdk";

const token = process.env.EXPYS_MEMBER_TOKEN;
if (!token) {
  throw new Error(
    "Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)",
  );
}

const expys = initialize({
  baseUrl: process.env.EXPYS_BASE_URL,
  environment: "sandbox",
  token,
});

async function main(): Promise<void> {
  // externalUserID names the member when a machine token calls on their behalf.
  const eligibility = await expys.eligibility({
    externalUserID: process.env.EXPYS_EXTERNAL_USER_ID,
  });
  console.log(`tier: ${eligibility.tier}`);
  console.log(`wallet (from eligibility): ${eligibility.wallet.balance}`);

  const wallet = await expys.wallet();
  console.log(
    `wallet: balance=${wallet.balance} received=${wallet.amountReceived} ` +
      `spent=${wallet.amountSpent} ${wallet.currency.symbol} (${wallet.currency.name})`,
  );
}
curl
curl https://api.expys.com/v1/eligibility \
  -H "Authorization: Bearer YOUR_MEMBER_TOKEN"
The externalUserID query parameter is optional. Omit it and the call resolves to the member the token was minted for; pass it when a machine token acts on a specific member’s behalf.

Response

tier
string
required
The member’s tier. This is client-set on the member profile and flows through here - see Members.
wallet
Wallet
required
The member’s wallet, embedded so you can gate offers and show a balance without a second call.
The embedded Wallet has these fields:
FieldTypeDescription
balancenumberSpendable points available now.
amountReceivednumberLifetime points received.
amountSpentnumberLifetime points spent.
currency.namestringThe points-currency name.
currency.symbolstringThe points-currency symbol.
Tier comes from the member profile, not from the API. Set or change it server-side; this endpoint only reflects the current value. See Members for how tier is assigned.

Next steps

Wallet

Read the wallet directly, with lifetime totals and currency.

Members

How a member’s tier is set and flows into eligibility.