> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eligibility

> Read a member's tier and wallet in one call, so the app can gate offers and show balances up front.

`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.

<Note>
  These are **member-mode** calls: they use the member token, not the
  Org-API-Key. See [Authentication](/authentication). Whether you read sandbox or
  live data is selected by the key the token was minted from - see
  [Environments](/environments).
</Note>

## 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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  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})`,
    );
  }
  ```

  ```swift Swift theme={null}
  import ExpysSDK
  import Foundation

  @main
  struct EligibilityWalletExample {
    static func main() async throws {
      let environment = ProcessInfo.processInfo.environment
      guard let token = environment["EXPYS_MEMBER_TOKEN"] else {
        fatalError("Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)")
      }
      let baseURL =
        environment["EXPYS_BASE_URL"].flatMap(URL.init(string:))
        ?? ExpysConfiguration.defaultBaseURL

      let client = ExpysClient(
        configuration: ExpysConfiguration(token: token, environment: .sandbox, baseURL: baseURL)
      )

      // externalUserID names the member when a machine token calls on their behalf.
      let eligibility = try await client.eligibility(
        externalUserID: environment["EXPYS_EXTERNAL_USER_ID"]
      )
      print("tier: \(eligibility.tier)")
      print("wallet (from eligibility): \(eligibility.wallet.balance)")

      let wallet = try await client.wallet()
      print(
        "wallet: balance=\(wallet.balance) received=\(wallet.amountReceived) "
          + "spent=\(wallet.amountSpent) \(wallet.currency.symbol) (\(wallet.currency.name))"
      )
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  package com.expys.sdk.examples.eligibilitywallet

  import com.expys.sdk.ExpysClient
  import com.expys.sdk.ExpysConfiguration
  import kotlinx.coroutines.runBlocking

  fun main() = runBlocking {
    val token = System.getenv("EXPYS_MEMBER_TOKEN")
      ?: error("Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)")

    val client = ExpysClient.create(
      ExpysConfiguration(
        token = token,
        baseUrl = System.getenv("EXPYS_BASE_URL") ?: ExpysConfiguration.DEFAULT_BASE_URL,
      ),
    )

    // externalUserID names the member when a machine token calls on their behalf.
    val eligibility = client.eligibility(externalUserID = System.getenv("EXPYS_EXTERNAL_USER_ID"))
    println("tier: ${eligibility.tier}")

    val wallet = client.wallet()
    println("balance: ${wallet.balance} ${wallet.currency.symbol}")
    println("received: ${wallet.amountReceived}, spent: ${wallet.amountSpent}")
  }
  ```
</CodeGroup>

```bash curl theme={null}
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

<ResponseField name="tier" type="string" required>
  The member's tier. This is **client-set** on the member profile and flows
  through here - see [Members](/guides/members).
</ResponseField>

<ResponseField name="wallet" type="Wallet" required>
  The member's wallet, embedded so you can gate offers and show a balance without
  a second call.
</ResponseField>

The embedded `Wallet` has these fields:

| Field             | Type   | Description                     |
| ----------------- | ------ | ------------------------------- |
| `balance`         | number | Spendable points available now. |
| `amountReceived`  | number | Lifetime points received.       |
| `amountSpent`     | number | Lifetime points spent.          |
| `currency.name`   | string | The points-currency name.       |
| `currency.symbol` | string | The points-currency symbol.     |

<Tip>
  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](/guides/members) for how tier is assigned.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Wallet" icon="wallet" href="/guides/wallet">
    Read the wallet directly, with lifetime totals and currency.
  </Card>

  <Card title="Members" icon="user" href="/guides/members">
    How a member's tier is set and flows into eligibility.
  </Card>
</CardGroup>