Get User Offers

GET /v1/user-journeys/users/{externalId}/offers

Returns a list of active, non-expired personalized offers for the user. Offers are generated automatically by the AI offer engine based on the user’s lifecycle stage, engagement tier, and churn risk score.

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

Request Examples

cURL

curl https://api.gamifyhost.com/v1/user-journeys/users/user_12345/offers \
  -H "X-API-Key: pk_live_your_public_key"

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/user-journeys/users/user_12345/offers',
  {
    headers: { 'X-API-Key': 'pk_live_your_public_key' },
  }
);
const data = await response.json();

Flutter

final offers = await api.getUserOffers();

for (final offer in offers) {
  print('${offer.title} — ${offer.pointsValue} pts');
  print('Expires: ${offer.expiresAt}');
}

Response

{
  "status": "success",
  "data": {
    "offers": [
      {
        "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": "active",
        "expiresAt": "2026-03-08T12:00:00Z",
        "claimedAt": null,
        "metadata": {}
      }
    ]
  }
}

Offer Fields

Field	Type	Description
id	string	Unique offer ID (UUID)
externalId	string	The user this offer belongs to
offerType	string	Offer category (see table below)
gameType	string	Associated game type, if any
title	string	Human-readable offer title
description	string	Offer description for the user
pointsValue	integer	Points value of the offer
status	string	active, claimed, or expired
expiresAt	string	ISO 8601 expiry timestamp
claimedAt	string?	ISO 8601 claim timestamp, null if unclaimed
metadata	object	Additional offer metadata

Offer Types

Type	Trigger	Description
welcome_free_play	New users	Free spin with guaranteed prize
welcome_bonus	New users	Bonus points to get started
win_back_play	Churned users	High-value free spin to re-engage
return_bonus	Churned users	Bonus points for returning
retention_play	At-risk users (churn risk >= 60)	Guaranteed-win game
vip_play	Whale-tier users	High-stakes exclusive game
multiplier_bonus	Power users	Double points on next game
daily_free_spin	Active/regular users	Daily free spin

Notes

• Each user can have a maximum of 3 active offers at any time.
• Offers are generated automatically during the analytics cron job.
• Duplicate offer types are prevented — a user won’t receive two offers of the same type simultaneously.
• Users inactive for more than 60 days are excluded from offer generation.