Claim a promotion

Live

POST/api/v1/promotions/:id/claim

Member self-serve bonus claim — CASHBACK / FREE_CREDIT / DAILY_LOGIN only. The bonus is credited to the wallet atomically; if the promotion has a wager multiplier, a pending claim is created that locks withdrawals.

A promotion with a wager_multiplier creates a pending claim (visible at active-claim) that locks withdrawals until turnover completes — one without a multiplier closes immediately on grant.

Debounce the button on your UI too — the server already prevents concurrent double-grants (single transaction); a repeat click yields 6004/6006, never a second bonus.

Headers

Field	Type	Required	Description
Authorization	string	Yes	Used — send Bearer <member access_token>
X-Api-Key	string	Yes	Agent API key (ak_…) from the bo screen
X-Timestamp	string	Yes	Signing time in unix milliseconds (±300s skew allowed)
X-Nonce	string	Yes	Unique per-request value (UUIDv4) for replay protection
X-Signature	string	Yes	hex(HMAC-SHA256(secret, canonical)) — see the Authentication page
X-Player-IP	string	—	The player's real IP (IPv4/IPv6) — recommended (used in login history)
X-Player-UA	string	—	The player's User-Agent (optional — recorded in login history)
X-Request-Id	string	—	Your correlation id — echoed back as request_uuid (recommended)
x-lang	string	—	th (default) or en — the language of message

Path parameters

Field	Type	Required	Description
id	string	Yes	Promotion id (uuid) from the all-promotions list — must belong to the member's own agent.

Response

Fields in data

Field	Type	Required	Description
claim_id	string	—	Id of the claim just created
bonus_thb	string	—	Bonus credited to the wallet (THB)
balance	string	—	Wallet balance after the credit (THB)
day	number \| null	—	DAILY_LOGIN only: the streak day just granted (1-7, wraps weekly; a missed day resets to 1) — null for other types.

Response example

{
  "success": true,
  "code": 0,
  "message": "รับโปรโมชั่นสำเร็จ",
  "data": {
    "claim_id": "9d4c1f2a-6b8e-4d05-93a7-c51e0f8b2d46",
    "bonus_thb": "50.00",
    "balance": "175.50",
    "day": null
  },
  "request_uuid": "7f3e9c1b-5d24-48a6-b0e8-1c9f2d7a4e35"
}

Possible error codes

code	Name	HTTP	Message
6001	PROMOTION_NOT_FOUND	404	Promotion not foundPromotion not found under the member's agent, or it is not ACTIVE / outside its start-end window
6002	PROMOTION_NOT_CLAIMABLE	422	This promotion is granted automatically on depositThis type is not self-claimable — NEW_REGISTER / FIRST_DEPOSIT / GOLDEN_MINUTE are granted automatically on deposit
6003	PROMOTION_NOT_ELIGIBLE	422	Not eligible for this promotionNot eligible: wallet is not TRANSFER mode · member tier not in eligible_tiers · today's deposits below min_deposit_thb · computed bonus is 0 (e.g. CASHBACK with no deposit today) · promotion budget exhausted
6004	PROMOTION_ALREADY_CLAIMED	409	Promotion already claimedClaim cap reached — lifetime or per-day (CASHBACK and DAILY_LOGIN are always once per Bangkok day)
6006	PROMOTION_ACTIVE_CLAIM_EXISTS	409	You have an active promotion in progressA previous bonus is still pending turnover (see active-claim) — it must clear before claiming again
6007	PROMOTION_BALANCE_TOO_HIGH	422	Balance must be below the threshold to claimCurrent balance ≥ the promotion's require_balance_below_thb gate (offered only when the balance is low)
6008	PROMOTION_TURNOVER_NOT_MET	400	Turnover requirement not met to claim this promotionFREE_CREDIT with a min_turnover_thb gate — bet volume since the previous claim has not reached it
9002	SERVICE_UNAVAILABLE	503	Service unavailableThe bonus system is temporarily unavailable — retry later
1001	UNAUTHORIZED	401	Unauthorized
1007	TOKEN_INVALID	401	Token invalid