Member Management

Complete guide to managing loyalty program members.

Overview

The Member Data Service handles all member-related operations:

• Member registration and profiles
• Points management
• Tier assignment
• Membership programs
• Pass associations

Member Registration

Basic Registration

curl -X POST https://member.walletpass.ai/v1/members/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_id": "MEMBER-001",
    "member_name": "John Doe",
    "member_email": "john@example.com",
    "phone_number": "+1234567890"
  }'

Required Fields

• member_id - Unique identifier for the member
• member_name - Member's full name
• member_email - Member's email address

Optional Fields

• phone_number - Phone number for SMS distribution
• style_group_id - Style group for dynamic pass styling
• date_of_birth - Date of birth
• address, city, state, zip_code, country - Address information

Getting Member Information

Get Single Member

curl -H "X-API-Key: wp_your_api_key" \
  https://member.walletpass.ai/v1/members/MEMBER-001

Response:

{
  "status": "success",
  "data": {
    "id": "member-uuid",
    "member_id": "MEMBER-001",
    "member_name": "John Doe",
    "member_email": "john@example.com",
    "phone_number": "+1234567890",
    "points": 150,
    "tier": "silver",
    "status": "active",
    "passes": [
      {
        "pass_id": "pass-uuid-1",
        "pass_type": "apple",
        "created_at": "2025-01-09T10:30:00Z"
      }
    ],
    "created_at": "2025-01-09T10:30:00Z",
    "updated_at": "2025-01-09T10:30:00Z"
  }
}

The response includes:

• Member profile information
• Current points and tier
• All associated passes (Apple and Google)
• Timestamps

Points Management

Points Operations

Three operations are available:

1. Add - Increases current balance
2. Subtract - Decreases current balance (never below 0)
3. Set - Overwrites current balance

Add Points

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001/points \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "points": 25,
    "operation": "add",
    "description": "Purchase bonus"
  }'

Use Cases:

• Purchase rewards
• Welcome bonuses
• Referral bonuses
• Special promotions

Subtract Points (Redeem)

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001/points \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "points": 10,
    "operation": "subtract",
    "description": "Reward redeem"
  }'

Use Cases:

• Reward redemption
• Discount application
• Points expiration

Note: Points cannot go below 0. If you try to subtract more points than available, the balance will be set to 0.

Set Points (Admin Override)

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001/points \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "points": 100,
    "operation": "set",
    "description": "Admin adjustment"
  }'

Use Cases:

• Manual corrections
• Account adjustments
• Administrative overrides

Points Transaction History

All points operations are logged in the points_transactions table for audit purposes.

Tier Management

Automatic Tier Assignment

Tiers are automatically assigned based on points when:

• Membership program is defined
• Member points are updated

Define Membership Program

curl -X POST https://member.walletpass.ai/v1/memberships \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "name": "Loyalty Program",
    "tiers": [
      {
        "tier_name": "bronze",
        "min_points": 0,
        "max_points": 100
      },
      {
        "tier_name": "silver",
        "min_points": 101,
        "max_points": 200
      },
      {
        "tier_name": "gold",
        "min_points": 201,
        "max_points": 0
      }
    ]
  }'

Tier Rules

• min_points - Minimum points required for tier
• max_points - Maximum points for tier (0 = unlimited)
• Tiers are evaluated in order
• Member is assigned to the first matching tier

Example Flow

1. Member starts with 0 points → Bronze tier
2. Member earns 150 points → Silver tier (auto-updated)
3. Member earns 250 points → Gold tier (auto-updated)

Get Membership Program

curl -H "X-API-Key: wp_your_api_key" \
  https://member.walletpass.ai/v1/memberships

Updating Member Information

Update Member Profile

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_name": "John Updated",
    "phone_number": "+9876543210",
    "style_group_id": "style-group-uuid"
  }'

Updateable Fields

• member_name
• member_email
• phone_number
• style_group_id
• Address fields
• date_of_birth

Member Status

Status Values

• active - Member is active (default)
• suspended - Member is temporarily suspended
• inactive - Member is inactive

Update Status

Status can be updated via the member update endpoint:

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "status": "suspended"
  }'

Multi-Pass Support

Member with Multiple Passes

Members can have multiple passes of different types:

{
  "member_id": "MEMBER-001",
  "passes": [
    {
      "pass_id": "pass-1",
      "pass_type": "apple",
      "created_at": "2025-01-09T10:30:00Z"
    },
    {
      "pass_id": "pass-2",
      "pass_type": "google",
      "pass_url": "https://pay.google.com/...",
      "created_at": "2025-01-09T10:30:00Z"
    }
  ]
}

Pass Association

Passes are automatically associated with members when created via:

• POST /v1/passes/create-from-member
• POST /v1/passes/stylegroup/create-from-member

Best Practices

1. Unique Member IDs - Use consistent, unique identifiers
2. Points Descriptions - Always include descriptions for audit trail
3. Tier Design - Design tiers with clear point ranges
4. Status Management - Use status to manage member lifecycle
5. Data Validation - Validate email and phone number formats

Common Workflows

New Member Onboarding

1. Register member
2. Add welcome bonus points
3. Create Apple Wallet pass
4. Send pass via SMS

Points Redemption

1. Check member points
2. Subtract points for redemption
3. Pass automatically updates on device

Tier Upgrade

1. Member earns points
2. Points updated via API
3. Tier automatically recalculated
4. Pass style updated (if using style groups)
5. Pass automatically updates on device