Get Fulfillments

Overview

Returns all claimed offers, perks, and grants for the authenticated member. This includes items that have been redeemed using points, along with their verification codes and status.

Fulfillments represent the "claimed items" in a member's wallet - things they've spent points on.

Authentication

Requires a valid Clerk JWT token in the Authorization header.

Query Parameters

statusquerystring

Filter by fulfillment status group

Available values:

"active" - claimed, pending_approval, modified, approved
"completed" - fulfilled
"cancelled" - rejected, cancelled, expired

sourceTypequerystring

Filter by source type

Available values: "offer", "perk", "grant"

propertyIdquerynumber

Filter by property ID for property-specific redemptions

limitquerynumber

Maximum number of fulfillments to return (default: 20, max: 100)

offsetquerynumber

Number of fulfillments to skip for pagination (default: 0)

Request

curl -X GET "http://localhost:3000/v1/members/me/wallet/fulfillments?status=active&limit=10" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"

Response

itemsarrayrequired

List of fulfillments

array items

idstringrequired

Fulfillment ID (UUID)

sourceTypestringrequired

Source type: "offer", "perk", or "grant"

namestringrequired

Name of the claimed item

shortDescriptionstring

Brief description of the item

catalogTypestring

Catalog type: "offer" or "perk"

redemptionTypestring

How this item is redeemed: "instant", "manual", "property_specific"

propertyNamestring

Property name for property-specific redemptions

reservationIdstring

External reservation ID if tied to a specific booking

statusstringrequired

Current fulfillment status

approvalStatusstring

Approval status for items requiring approval

pointsChargednumber

Points spent to claim this item

claimedAtstringrequired

ISO 8601 timestamp when item was claimed

fulfilledAtstring

ISO 8601 timestamp when item was fulfilled

expiresAtstring

ISO 8601 timestamp when item expires

responseDeadlinestring

ISO 8601 timestamp for response deadline (for items requiring approval)

verificationCodestring

Code to verify redemption with property/vendor

activationCodestring

Code to activate the redemption

qrCodeUrlstring

URL to QR code for mobile redemption

mediaobject

Media assets for the item

properties

heroImageUrlstring

Hero image URL

cardImageUrlstring

Card/thumbnail image URL

howToRedeemstring

Instructions on how to redeem this item

metadataobject

Additional metadata specific to the fulfillment type

totalnumberrequired

Total number of fulfillments matching filters

statusCountsobjectrequired

Count of fulfillments by status group

properties

activenumberrequired

Number of active fulfillments

completednumberrequired

Number of completed fulfillments

cancellednumberrequired

Number of cancelled fulfillments

offsetnumberrequired

Current pagination offset

limitnumberrequired

Current pagination limit

Response

200 Response

{
  "items": [
    {
      "id": "fulfill_550e8400-e29b-41d4-a716-446655440000",
      "sourceType": "offer",
      "name": "Suite Upgrade",
      "shortDescription": "Complimentary upgrade to next available suite",
      "catalogType": "offer",
      "redemptionType": "property_specific",
      "propertyName": "Luxury Resort & Spa",
      "reservationId": "ABC123",
      "status": "approved",
      "approvalStatus": "approved",
      "pointsCharged": 1500,
      "claimedAt": "2024-04-10T09:15:00Z",
      "fulfilledAt": null,
      "expiresAt": "2024-04-20T23:59:59Z",
      "responseDeadline": "2024-04-15T12:00:00Z",
      "verificationCode": "SUITE-2024-789",
      "activationCode": null,
      "qrCodeUrl": "https://cdn.journey.com/qr/fulfill_550e8400.png",
      "media": {
        "heroImageUrl": "https://cdn.journey.com/offers/suite-upgrade-hero.jpg",
        "cardImageUrl": "https://cdn.journey.com/offers/suite-upgrade-card.jpg"
      },
      "howToRedeem": "Present verification code at check-in or call the property directly.",
      "metadata": {
        "currentRoomType": "Standard King",
        "requestedRoomType": "Junior Suite",
        "confirmedRoomType": "Executive Suite"
      }
    },
    {
      "id": "fulfill_550e8400-e29b-41d4-a716-446655440001",
      "sourceType": "perk",
      "name": "Free Breakfast",
      "shortDescription": "Complimentary breakfast for two at resort restaurant",
      "catalogType": "perk",
      "redemptionType": "instant",
      "propertyName": "Downtown Hotel",
      "reservationId": "XYZ789",
      "status": "fulfilled",
      "approvalStatus": null,
      "pointsCharged": 500,
      "claimedAt": "2024-04-01T14:30:00Z",
      "fulfilledAt": "2024-04-05T08:00:00Z",
      "expiresAt": null,
      "responseDeadline": null,
      "verificationCode": "BREAKFAST-456",
      "activationCode": null,
      "qrCodeUrl": null,
      "media": {
        "heroImageUrl": "https://cdn.journey.com/perks/breakfast-hero.jpg",
        "cardImageUrl": "https://cdn.journey.com/perks/breakfast-card.jpg"
      },
      "howToRedeem": "Show verification code to restaurant host.",
      "metadata": null
    }
  ],
  "total": 8,
  "statusCounts": {
    "active": 3,
    "completed": 4,
    "cancelled": 1
  },
  "offset": 0,
  "limit": 10
}