Skip to content
Reward Loyalty
Get it · $349
Reward Loyalty
Get it · $349 Sign in
Documentation
Back to Home Buy Reward Loyalty

Member endpoints.

Complete endpoint reference for member-scoped agent operations.

Jul 21, 2026

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.
  • Read-only, with two exceptions: Members can view their balance, cards, transactions, and rewards. The only writes are 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

Aspect Partner Key Member Key
Prefix rl_agent_ rl_member_
Default expiration None (permanent) 90 days
Max keys Configurable by admin (default: 5) Fixed at 3
Scope presets View Only, POS, Full Management, Full View Only, Full Access

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

The API accepts updates to name and locale only. Email changes require the full authentication flow in 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 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. It does not 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
  }
}

Passes

Prepaid passes the member holds, read-only.

List passes

GET /api/agent/v1/member/passes

Scope: read

Returns the member's passes across all partners, newest first. Each carries a validity-aware effective_status and the selling prepaid_pass template summary.

Get a pass

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

Scope: read

Returns one held pass with its ledger history.

Achievements

The member's achievement progress and earned collection, read-only. Mirrors the member's own achievements page.

Get achievements

GET /api/agent/v1/member/achievements

Scope: read

Query parameters: business (partner UUID; defaults to the business with the member's most recent loyalty activity), plus page/per_page for the earned collection.

Returns the member's businesses that run achievements (businesses[], each with partner_id, business_name, selected), and for the selected business: the next target, the in-progress and upcoming milestones with progress and any active reward preview, the live weekly-run state, and the paginated earned collection. Each earned entry carries its reward state: delivered links the real artifact (artifact_type and artifact_id), a reward still being added reads pending, and a reward that could not be added reads unavailable; failure details (error codes, retries) never appear on a member surface. Voided achievements never appear either.

Returns business: null when no business runs achievements for this member.

Discover

Members discover cards in two ways:

  1. Homepage browsing: Live resources with is_visible_by_default enabled appear on the public homepage
  2. QR code / shared link: Members can reach any live loyalty card, stamp card, or voucher 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) 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:

Format Example
Full card URL https://example.com/en-us/card/{uuid}
Follow link URL https://example.com/en-us/follow/{uuid}
Stamp card URL https://example.com/en-us/stamp-card/{uuid}
Voucher URL https://example.com/en-us/voucher/{uuid}
Raw UUID 019cc3a5-51cb-7315-97e1-69147399f94d
Unique identifier 344-319-665-971

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 two scope presets:

Preset Scopes Use Case
View Only read Balance checks, browsing rewards
Full Access read, write:redeem, write:profile Full wallet functionality

For webshop integrations

The member API serves 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

This flow serves custom storefronts; WooCommerce stores can use the native WooCommerce integration instead.

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

Cookies on this site.

Google Analytics runs only if you allow it. Cookie policy