# Get Available Perks
> Source: /api-reference/members/loyalty/get-available-perks
> Get tier-based perks available to the member, optionally filtered by property
> Endpoint: GET /members/me/loyalty/entitlements/perks

## Overview [#overview]

Returns tier-based perks available to the member based on their current membership tier. Perks are benefits that members receive as part of their tier status, typically at no additional cost.

Unlike offers (which cost points), perks are entitlements that come with membership tiers.

## Authentication [#authentication]

Requires a valid Clerk JWT token in the Authorization header.

## Query Parameters [#query-parameters]

<ParamField query="propertyId" type="string">
  Property document ID to filter perks for a specific property
</ParamField>

<ParamField query="reservationId" type="string">
  Reservation external ID for in-stay context (UUID from core.reservations.external_reservation_id)
</ParamField>

<ParamField query="redemptionType" type="string">
  Filter by redemption type: "direct", "requireApproval", "timelessStay", etc.
</ParamField>

<ParamField query="includePropertyPerks" type="boolean">
  Include property-specific perks (default: true)
</ParamField>

<ParamField query="includeGlobalPerks" type="boolean">
  Include global perks available everywhere (default: true)
</ParamField>

<RequestExample>

```bash cURL
curl -X GET "http://localhost:3000/v1/members/me/loyalty/entitlements/perks?propertyId=abc123xyz&includePropertyPerks=true" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"
```

```typescript TypeScript
const response = await fetch('http://localhost:3000/v1/members/me/loyalty/entitlements/perks?propertyId=abc123xyz&includePropertyPerks=true', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_CLERK_JWT'
  }
});

const perks = await response.json();
```

</RequestExample>

## Response [#response]

<ResponseField name="globalPerks" type="array" required>
  Global perks available everywhere
  
  <Expandable title="array items">
    <ResponseField name="perkId" type="string" required>
      Perk document ID (public identifier)
    </ResponseField>
    
    <ResponseField name="name" type="string" required>
      Display name of the perk
    </ResponseField>
    
    <ResponseField name="description" type="string">
      Full description of what this perk provides
    </ResponseField>
    
    <ResponseField name="redemptionType" type="string" required>
      How perk is redeemed: "direct", "requireApproval", "timelessStay", etc.
    </ResponseField>
    
    <ResponseField name="minTierLevel" type="number" required>
      Minimum tier level required to access this perk
    </ResponseField>
    
    <ResponseField name="heroImage" type="object">
      Hero image for detailed view
      
      <Expandable title="properties">
        <ResponseField name="url" type="string" required>
          Image URL
        </ResponseField>
        
        <ResponseField name="alt" type="string">
          Alt text for accessibility
        </ResponseField>
        
        <ResponseField name="width" type="number">
          Image width in pixels
        </ResponseField>
        
        <ResponseField name="height" type="number">
          Image height in pixels
        </ResponseField>
      </Expandable>
    </ResponseField>
    
    <ResponseField name="cardImage" type="object">
      Card image for list/grid display
      
      <Expandable title="properties">
        <ResponseField name="url" type="string" required>
          Image URL
        </ResponseField>
        
        <ResponseField name="alt" type="string">
          Alt text for accessibility
        </ResponseField>
      </Expandable>
    </ResponseField>
    
    <ResponseField name="howToRedeem" type="string">
      Instructions for redeeming this perk
    </ResponseField>
    
    <ResponseField name="isEligible" type="boolean" required>
      Whether member can currently use this perk
    </ResponseField>
    
    <ResponseField name="eligibilityReason" type="string">
      Reason if not eligible (e.g., "Tier too low", "Requires active stay")
    </ResponseField>
    
    <ResponseField name="sourceType" type="string" required>
      Always "global" for global perks
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="propertyPerks" type="array" required>
  Property-specific perks with possible overrides
  
  <Expandable title="array items">
    <ResponseField name="perkId" type="string" required>
      Perk document ID (public identifier)
    </ResponseField>
    
    <ResponseField name="name" type="string" required>
      Display name of the perk
    </ResponseField>
    
    <ResponseField name="description" type="string">
      Full description of what this perk provides
    </ResponseField>
    
    <ResponseField name="redemptionType" type="string" required>
      How perk is redeemed
    </ResponseField>
    
    <ResponseField name="minTierLevel" type="number" required>
      Minimum tier level required
    </ResponseField>
    
    <ResponseField name="heroImage" type="object">
      Hero image for detailed view
    </ResponseField>
    
    <ResponseField name="cardImage" type="object">
      Card image for list/grid display
    </ResponseField>
    
    <ResponseField name="howToRedeem" type="string">
      Instructions for redeeming this perk
    </ResponseField>
    
    <ResponseField name="isEligible" type="boolean" required>
      Whether member can currently use this perk
    </ResponseField>
    
    <ResponseField name="eligibilityReason" type="string">
      Reason if not eligible
    </ResponseField>
    
    <ResponseField name="sourceType" type="string" required>
      Always "property" for property perks
    </ResponseField>
    
    <ResponseField name="propertyId" type="string" required>
      Property document ID where this perk is available
    </ResponseField>
    
    <ResponseField name="propertyName" type="string">
      Name of the property offering this perk
    </ResponseField>
    
    <ResponseField name="overriddenName" type="string">
      Custom name for this perk at this property (if different)
    </ResponseField>
    
    <ResponseField name="overriddenDescription" type="string">
      Custom description for this perk at this property (if different)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number" required>
  Total count of all perks (global + property)
</ResponseField>

<ResponseExample>

```json 200 Response
{
  "globalPerks": [
    {
      "perkId": "perk_timeless_stay",
      "name": "Timeless Stay",
      "description": "Flexible check-in and check-out times to maximize your experience",
      "redemptionType": "timelessStay",
      "minTierLevel": 2,
      "heroImage": {
        "url": "https://cdn.journey.com/perks/timeless-stay-hero.jpg",
        "alt": "Timeless Stay Hero",
        "width": 1200,
        "height": 600
      },
      "cardImage": {
        "url": "https://cdn.journey.com/perks/timeless-stay-card.jpg",
        "alt": "Timeless Stay"
      },
      "howToRedeem": "Contact property directly to arrange custom check-in/out times",
      "isEligible": true,
      "sourceType": "global"
    },
    {
      "perkId": "perk_suite_elevation", 
      "name": "Suite Elevation",
      "description": "Complimentary upgrade to the next available suite category",
      "redemptionType": "suiteElevation",
      "minTierLevel": 3,
      "heroImage": {
        "url": "https://cdn.journey.com/perks/suite-elevation-hero.jpg",
        "alt": "Suite Elevation Hero"
      },
      "cardImage": {
        "url": "https://cdn.journey.com/perks/suite-elevation-card.jpg",
        "alt": "Suite Elevation"
      },
      "howToRedeem": "Request during booking or at check-in",
      "isEligible": false,
      "eligibilityReason": "Requires tier level 3 (current: 2)",
      "sourceType": "global"
    }
  ],
  "propertyPerks": [
    {
      "perkId": "perk_spa_access",
      "name": "Spa Access",
      "description": "Complimentary access to spa facilities including sauna, steam room, and relaxation areas",
      "redemptionType": "direct",
      "minTierLevel": 1,
      "cardImage": {
        "url": "https://cdn.journey.com/perks/spa-access-card.jpg",
        "alt": "Spa Access"
      },
      "howToRedeem": "Present your room key at spa reception",
      "isEligible": true,
      "sourceType": "property",
      "propertyId": "prop_luxury_resort",
      "propertyName": "Luxury Resort & Spa",
      "overriddenDescription": "VIP access to our award-winning spa including heated pool, jacuzzi, and meditation garden"
    }
  ],
  "total": 3
}
```

</ResponseExample>

## Perk Types [#perk-types]

### Global Perks [#global-perks]
- **Availability**: Available at all participating properties
- **Consistency**: Same benefits across properties
- **Examples**: Timeless Stay, Suite Elevation, Priority Service

### Property Perks [#property-perks]
- **Availability**: Specific to individual properties
- **Customization**: May have property-specific names/descriptions
- **Examples**: Spa access, dining credits, local experiences

## Eligibility Factors [#eligibility-factors]

### Tier Level [#tier-level]
- **Minimum Required**: Each perk specifies minimum tier level
- **Current Tier**: Checked against member's current tier status
- **Upgrade Path**: Ineligible perks show what tier is needed

### Property Context [#property-context]
- **Property Filter**: When filtering by property, shows relevant perks
- **Reservation Context**: Some perks require active stay
- **Location**: Property perks only available at specific locations

### Stay Requirements [#stay-requirements]
- **Active Stay**: Some perks require current reservation
- **Future Stay**: Some perks can be used for upcoming reservations
- **Check-in Status**: Timing may affect availability

## Related Endpoints [#related-endpoints]

- [Get Member Profile](/api-reference/members/me/profile/get-profile) - Check current tier level