Reward methods
Client methods for balances, lotteries, entries and claims.
On this page
getTokenBalance
Reads the participant’s token balance. Needs a participant token.
getTokenBalance(): Promise<TokenBalance>Returns: A Promise of { tokens, platformUserId, externalUserId, available?, pending?, lifetime? }.
getTokenBalanceHistory
Reads the participant’s token transactions, newest first. Needs a participant token.
getTokenBalanceHistory(options?: { page?: number; perPage?: number }): Promise<TokenLedgerHistoryResult>| Parameter | Type | Description |
|---|---|---|
options.page | number | Page number. |
options.perPage | number | Items per page. |
Returns: A Promise of { items, currentPage, lastPage, total, perPage }.
getLotteries
Lists lotteries visible to the participant. Needs a participant token.
getLotteries(options?: GetLotteriesOptions): Promise<LotteryListResult>| Parameter | Type | Description |
|---|---|---|
options.filter | LotteryFilter | active (default), upcoming, completed or all. |
options.page | number | Page number. |
options.perPage | number | Items per page. |
Returns: A Promise of { lotteries, pagination }.
getLottery
Loads one lottery with its prizes and the participant’s own entry count. Needs a participant token.
getLottery(lotteryId: number): Promise<LotteryDetail>| Parameter | Type | Description |
|---|---|---|
lotteryId required | number | Lottery ID. |
Returns: A Promise of LotteryDetail.
enterLottery
Spends tokens to buy entries. Create one idempotency key for each purchase attempt and reuse it when you retry after an uncertain response. Needs a participant token.
enterLottery(lotteryId: number, options: EnterLotteryOptions): Promise<LotteryPurchase>| Parameter | Type | Description |
|---|---|---|
lotteryId required | number | Lottery ID. |
options.entryCount required | number | Entries to buy, 1 to 100. |
options.idempotencyKey required | string | Unique key for this purchase attempt. |
Returns: A Promise of LotteryPurchase: { id, lotteryId, entryCount, unitCostTokens, totalCostTokens, status, ticketNumbers, eligibilitySnapshot? }.
import { createIdempotencyKey } from "@adquest/sdk";
const purchase = await client.enterLottery(4, {
entryCount: 2,
idempotencyKey: createIdempotencyKey(),
});getMyLotteryEntries
Lists the participant’s entries and purchases for one lottery. Needs a participant token.
getMyLotteryEntries(lotteryId: number): Promise<MyLotteryEntriesResult>| Parameter | Type | Description |
|---|---|---|
lotteryId required | number | Lottery ID. |
Returns: A Promise of { entries, purchases, entryCount }.
getLotteryResults
Returns the winners once the lottery is completed. Before that, winners is empty. Needs a participant token.
getLotteryResults(lotteryId: number): Promise<LotteryResults>| Parameter | Type | Description |
|---|---|---|
lotteryId required | number | Lottery ID. |
Returns: A Promise of { lifecycleStatus, winners }.
getMyClaims
Lists the prizes the participant has won. Needs a participant token.
getMyClaims(): Promise<LotteryClaim[]>Returns: A Promise of LotteryClaim[].
submitLotteryClaim
Submits the winner’s claim details. A submitted claim is not a promise that fulfillment is complete. Needs a participant token.
submitLotteryClaim(claimId: number, payload: SubmitClaimPayload): Promise<LotteryClaim>| Parameter | Type | Description |
|---|---|---|
claimId required | number | Claim ID from getMyClaims. |
payload required | Record<string, unknown> | The claim details the prize requires. |
Returns: A Promise of the updated LotteryClaim.