Get Available Perks

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

Requires a valid Clerk JWT token in the Authorization header.

Query Parameters

propertyIdquerystring

Property document ID to filter perks for a specific property

reservationIdquerystring

Reservation external ID for in-stay context (UUID from core.reservations.external_reservation_id)

redemptionTypequerystring

Filter by redemption type: "direct", "requireApproval", "timelessStay", etc.

includePropertyPerksqueryboolean

Include property-specific perks (default: true)

includeGlobalPerksqueryboolean

Include global perks available everywhere (default: true)

Request

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

Response

globalPerksarrayrequired

Global perks available everywhere

array items

perkIdstringrequired

Perk document ID (public identifier)

namestringrequired

Display name of the perk

descriptionstring

Full description of what this perk provides

redemptionTypestringrequired

How perk is redeemed: "direct", "requireApproval", "timelessStay", etc.

minTierLevelnumberrequired

Minimum tier level required to access this perk

heroImageobject

Hero image for detailed view

properties

urlstringrequired

Image URL

altstring

Alt text for accessibility

widthnumber

Image width in pixels

heightnumber

Image height in pixels

cardImageobject

Card image for list/grid display

properties

urlstringrequired

Image URL

altstring

Alt text for accessibility

howToRedeemstring

Instructions for redeeming this perk

isEligiblebooleanrequired

Whether member can currently use this perk

eligibilityReasonstring

Reason if not eligible (e.g., "Tier too low", "Requires active stay")

sourceTypestringrequired

Always "global" for global perks

propertyPerksarrayrequired

Property-specific perks with possible overrides

array items

perkIdstringrequired

Perk document ID (public identifier)

namestringrequired

Display name of the perk

descriptionstring

Full description of what this perk provides

redemptionTypestringrequired

How perk is redeemed

minTierLevelnumberrequired

Minimum tier level required

heroImageobject

Hero image for detailed view

cardImageobject

Card image for list/grid display

howToRedeemstring

Instructions for redeeming this perk

isEligiblebooleanrequired

Whether member can currently use this perk

eligibilityReasonstring

Reason if not eligible

sourceTypestringrequired

Always "property" for property perks

propertyIdstringrequired

Property document ID where this perk is available

propertyNamestring

Name of the property offering this perk

overriddenNamestring

Custom name for this perk at this property (if different)

overriddenDescriptionstring

Custom description for this perk at this property (if different)

totalnumberrequired

Total count of all perks (global + property)

Response

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
}