Members APILoyalty

Claim Offer

Purchase an offer with points and create a fulfillment

POST/members/me/loyalty/offers/{offerId}/claim

Overview

Claims an offer for the authenticated member by deducting the required points from their wallet and creating a fulfillment with verification codes. This action is irreversible once completed.

Authentication

Requires a valid Clerk JWT token in the Authorization header.

Path Parameters

offerIdpathstringrequired

Offer document ID to claim

Request Body

propertyIdbodystring

Property document ID where offer will be redeemed. Required for property-specific offers.

reservationIdbodystring

Reservation external ID for in-stay offers (from core.reservations.external_id)

Request

curl -X POST "http://localhost:3000/v1/members/me/loyalty/offers/offer_spa_discount/claim" \
  -H "Authorization: Bearer YOUR_CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "prop_luxury_resort",
    "reservationId": "RES-12345"
  }'

Response

successbooleanrequired

Whether the offer was successfully claimed

fulfillmentIdstring

UUID of the created fulfillment record

redemptionTypestring

How this offer should be redeemed

verificationCodestring

Primary verification code for redeeming at property

activationCodestring

Secondary activation code if needed

qrCodeUrlstring

URL to QR code for mobile scanning

pointsChargednumber

Number of points deducted from wallet

statusstring

Initial status of the fulfillment (usually "claimed")

claimedAtstringrequired

ISO 8601 timestamp when offer was claimed

responseDeadlinestring

ISO 8601 timestamp for response deadline (for approval-based offers)

Response

{
  "success": true,
  "fulfillmentId": "fulfill_550e8400-e29b-41d4-a716-446655440000",
  "redemptionType": "propertySpecific",
  "verificationCode": "SPA-DISC-2024-789",
  "activationCode": null,
  "qrCodeUrl": "https://cdn.journey.com/qr/fulfill_550e8400.png",
  "pointsCharged": 1500,
  "status": "claimed",
  "claimedAt": "2024-04-15T14:30:00Z",
  "responseDeadline": null
}

Claim Process

Validation

Offer Existence: Verifies offer exists and is active
Member Eligibility: Checks tier level, points balance, property access
Property Context: Validates property and reservation IDs if required
Time Windows: Ensures claim is within valid time windows

Point Deduction

Immediate: Points are deducted from wallet immediately
Transaction Record: Creates a DEBIT transaction in wallet history
Balance Update: Wallet balance is updated in real-time

Fulfillment Creation

Fulfillment Record: Creates a fulfillment with unique ID
Verification Codes: Generates codes for property redemption
Status Setting: Initial status based on redemption type
Deadline Setting: Sets response deadlines for approval-based offers

Fulfillment Statuses

claimed

Meaning: Recently claimed, being processed
Next Step: Will move to "approved" or require property approval
Codes: May not be immediately available

pending_approval

Meaning: Waiting for property approval
Next Step: Property will approve/reject or modify
Codes: Not yet available until approved

approved

Meaning: Ready to use at property
Next Step: Member redeems using verification code
Codes: Available for redemption

Property Context Requirements

Property-Specific Offers

propertyId: Required - specifies where offer will be redeemed
reservationId: Optional - links to specific stay

In-Stay Offers

propertyId: Required - must match reservation property
reservationId: Required - must be member's active/future reservation

Global Offers

propertyId: Not required - can be used anywhere
reservationId: Not required - not tied to specific stay

Error Scenarios

Insufficient Points

Check: Use Get Balance first
Resolution: Member needs to earn more points or choose cheaper offer

Property Access

Check: Ensure member has reservation at specified property
Resolution: Provide correct property/reservation IDs

Offer Restrictions

Check: Review offer eligibility details
Resolution: Satisfy restriction requirements (e.g., active stay)

Time Windows

Check: Some offers have check-in time restrictions
Resolution: Claim within valid time window

Get Offer Details - Check eligibility before claiming
Get Fulfillments - View claimed offers
Get Wallet Balance - Check points balance

Get Offer Details

Get detailed information about a specific offer with eligibility status

Confirm Fulfillment Redeemed

Member confirms a claimed fulfillment as successfully redeemed