Journey Docs
Members APIWallet

Get Wallet Balance

Get comprehensive wallet balance and tier information

GET/members/me/wallet/balance

Overview

Returns comprehensive wallet balance including valid points, credit points, pending points, outstanding debt, net balance, total available points, debt status, and tier information with points to next tier.

This is the primary endpoint for displaying wallet status in member-facing applications.

Authentication

Requires a valid Clerk JWT token in the Authorization header.

Request

curl -X GET "http://localhost:3000/v1/members/me/wallet/balance" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"

Response

validBalancenumberrequired

VALID asset balance (net of earnings minus spend)

Points earned from stays that can be used for redemptions

creditBalancenumberrequired

CREDIT asset balance (promotional/early-access points)

Promotional points that can be spent but don't count toward tier progression

pendingPointsnumberrequired

Points currently in escrow waiting for reservation completion

outstandingDebtnumberrequired

Outstanding debt amount (negative balance)

netBalancenumberrequired

Net spendable balance (validBalance + creditBalance - outstandingDebt)

totalAvailablePointsnumberrequired

Total points available for spending (convenience aggregate)

Same as netBalance when positive, 0 when negative

hasDebtbooleanrequired

Whether the member has outstanding debt

tierEligiblePointsnumberrequired

Points earned this calendar year that count toward tier qualification

tierLevelnumberrequired

Current tier level (1 = Traveler/base tier)

tierNamestringrequired

Current tier name

pointsToNextTiernumber | nullrequired

Points needed to reach the next tier

null if already at the highest tier

nextTierNamestring | nullrequired

Name of the next tier

null if already at the highest tier

Response

{
  "validBalance": 12500,
  "creditBalance": 2000,
  "pendingPoints": 1800,
  "outstandingDebt": 0,
  "netBalance": 14500,
  "totalAvailablePoints": 14500,
  "hasDebt": false,
  "tierEligiblePoints": 8500,
  "tierLevel": 2,
  "tierName": "Explorer",
  "pointsToNextTier": 11500,
  "nextTierName": "Voyager"
}

Balance Types

Valid Balance

  • Source: Points earned from completed stays
  • Usage: Can be spent on redemptions
  • Tier Impact: Counts toward tier qualification
  • Expiration: Typically 2 years from earn date

Credit Balance

  • Source: Promotional points, bonuses, adjustments
  • Usage: Can be spent on redemptions
  • Tier Impact: Does NOT count toward tier qualification
  • Expiration: Varies by promotion terms

Pending Points

  • Source: Points in escrow for future/recent stays
  • Usage: Cannot be spent until converted to Valid
  • Conversion: Happens after checkout completion
  • Display: Usually shown as "Points Pending"

Debt Handling

When hasDebt: true:

  • Member cannot make new redemptions until debt is cleared
  • totalAvailablePoints will be 0 regardless of credit/valid balances
  • Debt typically occurs from:
    • Redemption refunds/adjustments
    • Booking cancellations after point spend
    • Administrative corrections

Tier Information

The tier fields provide context for member progression:

  • Current Status: tierLevel and tierName
  • Progression: pointsToNextTier and nextTierName
  • Annual Progress: tierEligiblePoints (current year)

When at the highest tier:

  • pointsToNextTier and nextTierName are null
  • Show celebration UI instead of progression

Update Profile

Update extended profile preferences

Get Wallet Activity

Get paginated recent activity for wallet

On this page

OverviewAuthenticationResponseBalance TypesValid BalanceCredit BalancePending PointsDebt HandlingTier InformationRelated Endpoints