Member Endpoints.

All member endpoints are prefixed with /api/agent/v1/member and require a member-scoped key (rl_member_).

Common Patterns

All member endpoints share these behaviors:

• Self-scoped — A member key can only access the key owner's own data. No cross-member access is possible.
• Mostly read-only — Members can view their balance, cards, transactions, and rewards. Write access is limited to profile updates and reward claims.
• JSON request/response — Send and receive application/json
• Pagination — List endpoints support ?page=1&per_page=25 query parameters

Key Differences from Partner Keys

Profile

Get Profile

GET /api/agent/v1/member/profile

Scope: read

Returns the member's own profile information.

Response:

{
  "data": {
    "id": "member-uuid",
    "name": "Jane Smith",
    "email": "[email protected]",
    "locale": "en_US",
    "unique_identifier": "454-925-184-086",
    "avatar": null,
    "is_anonymous": false,
    "has_interacted": true,
    "first_interaction_at": "2026-01-15T10:30:00+00:00",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Update Profile

PUT /api/agent/v1/member/profile

Scope: write:profile

Only name and locale can be updated via API. Email changes require the full authentication flow via the member dashboard.

{
  "name": "Jane Updated",
  "locale": "fr_FR"
}

Balance & Cards

Wallet Overview (All Balances)

GET /api/agent/v1/member/balance

Scope: read

Returns balances across all enrolled loyalty cards in a single call. This is the primary endpoint for webshop "wallet overview" widgets.

Member-facing responses intentionally omit club information. Clubs are internal routing and staff-access structures; members interact with cards.

Response:

{
  "data": [
    {
      "card_id": "card-uuid-1",
      "card_title": "Coffee Rewards",
      "balance": 250,
      "currency": "points"
    },
    {
      "card_id": "card-uuid-2",
      "card_title": "VIP Club",
      "balance": 1200,
      "currency": "points"
    }
  ]
}

List Cards

GET /api/agent/v1/member/cards

Scope: read

Paginated list of enrolled cards with richer detail than /balance, including member-specific balance and presentation fields.

Get Card

GET /api/agent/v1/member/cards/{id}

Scope: read

Returns a single card's details and member balance. Returns 404 if the member is not enrolled in this card.

Transaction History

All Transactions

GET /api/agent/v1/member/transactions

Scope: read

Returns the member's full transaction history across all cards. Sorted by most recent first, paginated.

Card Transactions

GET /api/agent/v1/member/transactions/{cardId}

Scope: read

Filtered transaction history for a specific card. Returns 404 if the member is not enrolled in this card.

Rewards

Browse Available Rewards

GET /api/agent/v1/member/rewards

Scope: read

Lists all rewards available on the member's enrolled cards. Each reward includes:

• Whether the member can afford it (based on current balance)
• The member's best balance across linked cards
• The reward's point cost

This enables "You need X more points" messaging in webshop UIs.

Claim a Reward

POST /api/agent/v1/member/rewards/{id}/claim

Scope: write:redeem

Submits a reward claim request. This does not directly deduct points — staff must confirm the redemption via the partner dashboard or partner agent API.

This preserves the platform's "staff confirms redemption" flow, which prevents self-serve fraud at physical locations.

Success Response (200):

{
  "data": {
    "status": "claim_submitted",
    "reward_id": "reward-uuid",
    "reward_title": "Free Coffee",
    "points_required": 100,
    "card_id": "card-uuid",
    "card_title": "Coffee Rewards",
    "current_balance": 250,
    "message": "Your claim has been submitted. A staff member will confirm it."
  }
}

Insufficient Balance (422):

{
  "error": true,
  "code": "INSUFFICIENT_BALANCE",
  "message": "Not enough points. You have 50, but this reward requires 100.",
  "details": {
    "balance": 50,
    "required": 100,
    "deficit": 50
  }
}

Discover

Members discover cards in two ways:

1. Homepage browsing — Live resources with is_visible_by_default enabled appear publicly
2. QR code / shared link — Any live loyalty card, stamp card, or voucher can be found by scanning a QR code or opening a direct link

Browse Discoverable Cards

GET /api/agent/v1/member/discover

Scope: read

Returns all cards (loyalty cards, stamp cards, and vouchers) currently visible on the homepage. Includes the member's enrollment status and balance for each card they follow.

Response:

{
  "data": {
    "cards": [
      {
        "type": "loyalty_card",
        "id": "card-uuid",
        "name": "Barista Club",
        "title": "Coffee Rewards",
        "description": "Earn points on every cup",
        "currency": "USD",
        "bg_color": "#C49A00",
        "text_color": "#ffffff",
        "is_following": true,
        "balance": 37519,
        "rewards_count": 4
      }
    ],
    "stamp_cards": [
      {
        "type": "stamp_card",
        "id": "stamp-card-uuid",
        "title": "Tea Lover Card",
        "stamps_required": 6,
        "stamp_icon": "✨",
        "reward_title": "Free Tea Time",
        "is_enrolled": true,
        "current_stamps": 3,
        "completed_count": 2
      }
    ],
    "vouchers": [
      {
        "type": "voucher",
        "id": "voucher-uuid",
        "title": "10% Off First Order",
        "code": "WELCOME10",
        "voucher_type": "percentage",
        "value": 10,
        "currency": "USD",
        "valid_until": "2026-12-31T23:59:59.000000Z"
      }
    ]
  }
}

Resolve a URL or Identifier

POST /api/agent/v1/member/discover/resolve

Scope: read

Resolves a card URL (from a QR code scan or shared link) or identifier to its full details. This is the primary endpoint for QR code scanning workflows.

Supported input formats:

Request:

{
  "url": "https://example.com/en-us/card/019cc3a5-51cb-7315-97e1-69147399f94d"
}

Or:

{
  "identifier": "344-319-665-971"
}

Follow a Card

POST /api/agent/v1/member/discover/follow

Scope: write:profile

Saves a loyalty card to the member's "My Cards" collection. Idempotent — following an already-followed card is a no-op.

{
  "card_id": "card-uuid"
}

Unfollow a Card

POST /api/agent/v1/member/discover/unfollow

Scope: write:profile

Removes a card from the member's "My Cards" collection.

{
  "card_id": "card-uuid"
}

Scope Presets

Member keys use simplified scope presets:

For Webshop Integrations

The member API is designed for the webshop POS flow:

1. During login: Use GET /member/balance to show wallet overview
2. On product page: Use GET /member/rewards to show "Use 100 points for 10% off"
3. At checkout: Combine with the partner API to award points on purchase
4. Post-purchase: Show updated balance via GET /member/balance

See Authentication for how to use both member and partner keys in a single integration.

Related Topics

• Managing Keys — Creating and managing member agent keys
• Scopes & Permissions — Scope inheritance and enforcement
• Error Handling — Understanding error responses
• Authentication — Key format and security model