Skip to main content
The wallet is a member’s points balance. wallet returns the spendable balance alongside lifetime received and spent totals, denominated in your org’s points currency.
These are member-mode calls: they use the member token, not the Org-API-Key. See Authentication. Whether you read sandbox or live balances is selected by the key the token was minted from - see Environments.

Get the wallet

wallet() calls GET /v1/wallet and returns a Wallet for the member the token was minted for. The snippet below reads the balance, totals, and currency (it also shows the wallet embedded in eligibility):
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/wallet \
  -H "Authorization: Bearer YOUR_MEMBER_TOKEN"

The Wallet schema

FieldTypeDescription
balancenumberSpendable points available now. This is what a redemption is checked against.
amountReceivednumberLifetime total of points the member has received.
amountSpentnumberLifetime total of points the member has spent.
currency.namestringThe points-currency name (for example, your org’s points brand).
currency.symbolstringThe points-currency symbol, for display next to amounts.
balance is the spendable amount and the figure a redemption is checked against - a redemption fails with INSUFFICIENT_POINTS when balance is below the offer’s pointsPrice. amountReceived and amountSpent are running lifetime totals and do not decrease when points are spent.

Minting and the ledger

Reading the wallet is member-mode, but minting points is server-side. Credit points and inspect the per-transaction ledger (walletTransactions) from your backend - see Points and wallet.

Next steps

Points and wallet

Server-side minting and the credit/debit transaction ledger.

Eligibility

Read tier and wallet together in one call.

Redemptions

Spend the balance by redeeming offers.