Claim Offer

POST /v1/user-journeys/users/{externalId}/offers/{offerId}/claim

Claims a specific offer for a user. The offer must be active and not expired. Once claimed, the offer status changes to claimed and an offer_claimed event is logged to the user’s timeline.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key

Path Parameters

Parameter	Type	Required	Description
externalId	string	Yes	The user’s external ID in your system
offerId	string	Yes	The offer ID (UUID) to claim

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/user-journeys/users/user_12345/offers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/claim \
  -H "X-API-Key: pk_live_your_public_key" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/user-journeys/users/user_12345/offers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/claim',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'pk_live_your_public_key',
      'Content-Type': 'application/json',
    },
  }
);
const data = await response.json();

Flutter

final claimed = await api.claimOffer(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
);

print('Claimed: ${claimed.title}');
print('Points: ${claimed.pointsValue}');
print('Status: ${claimed.status}');

Response

{
  "status": "success",
  "data": {
    "offer": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalId": "user_12345",
      "offerType": "welcome_free_play",
      "gameType": "spin_the_wheel",
      "title": "Welcome Free Spin",
      "description": "Try a free spin on us — new players get a guaranteed prize!",
      "pointsValue": 50,
      "status": "claimed",
      "expiresAt": "2026-03-08T12:00:00Z",
      "claimedAt": "2026-03-05T14:30:00Z",
      "metadata": {}
    }
  }
}

Error Responses

Status	Message	Description
400	Offer is no longer active	Offer was already claimed
400	Offer has expired	Offer’s expiry time has passed
404	Offer not found	Invalid offer ID or doesn’t belong to this user

Side Effects

When an offer is claimed:

1. The offer status changes from active to claimed
2. The claimedAt timestamp is set
3. An offer_claimed event is logged to the user’s event timeline with the offer’s pointsValue