Skip to content

Earn 30% on every license you refer. Join the affiliate program

$349
Get it · $349 Try demo
Sign in

Member endpoints.

Complete endpoint reference for member-scoped agent operations.

Sep 30, 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.
  • Member operations: Members can read their own data, update their profile, follow or unfollow cards, and check reward eligibility through the claim endpoint.
  • 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

This endpoint checks the member's reward eligibility and returns claim_submitted. It does not deduct points, save a pending claim, or notify staff. Your integration must arrange the staff handoff and use the normal redemption workflow to complete it.

The response message refers to staff confirmation, but this release does not create a pending task or notification. Treat it as an eligibility response.

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. Omitted pass_format or pass_format=1 returns visit passes. Add ?pass_format=2 to include monetary balances and retained claims still linked to the authenticated member. Format 2 distinguishes balance_type and includes the issuer contact and integer money amounts; it does not expose payment references, internal actor details, or claim tokens.

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. Reading an owned monetary pass requires pass_format=2; otherwise the API returns 409 MONETARY_PASS_FORMAT_REQUIRED. Money history includes posting amounts, currency, and balance changes. These endpoints do not spend or refund a balance. Removing the member account removes its authority to read retained financial records.

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.