Reference / @getenginex/sdk-igaming / BonusApi
BonusApi
Bonus campaigns and promo codes. Only listPublicOffers is public; the other methods require login.
Methods
claim()
claim(
input,options?):Promise<CampaignParticipation>
Redeems the reward of a qualified participation (campaigns with player_claim). Idempotent, like BonusApi.optIn: repeat with the same idempotencyKey so as not to redeem twice. The response is always validated in strict mode.
Parameters
input
participationId
string
options?
Returns
Promise<CampaignParticipation>
Example
const done = await igaming.bonus.claim({ participationId: participation.id }, { idempotencyKey: key })Throws
BONUS_ALREADY_CLAIMED (409) if the reward was already redeemed; BONUS_EXPIRED outside the redemption window and BONUS_NOT_ELIGIBLE if it has not qualified yet (HTTP 500 on the gateway: identify by the code); FAILED_PRECONDITION/KYC_REQUIRED (422); BONUS_NOT_FOUND (404); INVALID_ARGUMENT (400) for an id that is not a UUID; KEY_IN_USE (409); PAYLOAD_MISMATCH (422); VALIDATION_ERROR if the response comes outside the format (the redemption may have happened: check getParticipation); UNAUTHENTICATED without a session.
getOffer()
getOffer(
input,options?):Promise<CampaignOffer>
An offer available to the player.
Parameters
input
campaignId
string
options?
Returns
Promise<CampaignOffer>
Example
const offer = await igaming.bonus.getOffer({ campaignId })Throws
BONUS_NOT_FOUND (404) if the campaign does not exist or is not available; INVALID_ARGUMENT (400) if campaignId is not a UUID; UNAUTHENTICATED without a session.
getParticipation()
getParticipation(
input,options?):Promise<CampaignParticipation>
One of the player's participations.
Parameters
input
participationId
string
options?
Returns
Promise<CampaignParticipation>
Example
const p = await igaming.bonus.getParticipation({ participationId })Throws
BONUS_NOT_FOUND (404) if it does not exist (or belongs to another player); INVALID_ARGUMENT (400) if the id is not a UUID; UNAUTHENTICATED without a session.
listOffers()
listOffers(
input?,options?):Promise<CursorPage<CampaignOffer>>
Offers available to the logged-in player. Cursor-paginated.
Parameters
input?
options?
Returns
Promise<CursorPage<CampaignOffer>>
Example
const { items } = await igaming.bonus.listOffers()
const optIns = items.filter((o) => o.entryPolicy?.code === 'opt_in')Throws
INVALID_ARGUMENT (400) for an invalid pageSize; UNAUTHENTICATED without a session.
listParticipations()
listParticipations(
input?,options?):Promise<CursorPage<CampaignParticipation>>
The player's participations. Cursor-paginated.
Parameters
input?
options?
Returns
Promise<CursorPage<CampaignParticipation>>
Example
const { items } = await igaming.bonus.listParticipations()
const claimable = items.filter((p) => p.status === 'qualified')Throws
INVALID_ARGUMENT (400) for an invalid pageSize; UNAUTHENTICATED without a session.
listPublicOffers()
listPublicOffers(
input?,options?):Promise<CursorPage<CampaignOffer>>
Public catalog of offers (storefront, no login): it only describes the campaigns; eligibility, joining and participations require login. Cursor-paginated.
Parameters
input?
options?
Returns
Promise<CursorPage<CampaignOffer>>
Example
const { items, nextCursor } = await igaming.bonus.listPublicOffers({ pageSize: 20 })Throws
INVALID_ARGUMENT (400) for a pageSize that is not a positive integer; UNAUTHENTICATED (401) if the gateway does not resolve the operator by the domain.
optIn()
optIn(
input,options?):Promise<CampaignParticipation>
Joins an opt_in campaign. Idempotent: it sends Idempotency-Key — generated on every call, or the one in options.idempotencyKey — and keeps it on the retry after renewing the session; to repeat after NETWORK_ERROR/TIMEOUT without joining twice, generate the key beforehand and pass the same one on both attempts. The response is always validated in strict mode.
Parameters
input
options?
Returns
Promise<CampaignParticipation>
Example
const participation = await igaming.bonus.optIn(
{ campaignId: offer.campaignId, campaignVersionId: offer.campaignVersionId, termsAcceptance: { locale: 'pt-BR', termsRevision: text.termsRevision } },
{ idempotencyKey: key },
)Throws
BONUS_NOT_ELIGIBLE if the player cannot join; BONUS_EXPIRED outside the entry window (the gateway still returns these two with HTTP 500: identify by the code); BONUS_NOT_FOUND (404); ALREADY_EXISTS/BONUS_ALREADY_CLAIMED (409) if the player already participates; KYC_REQUIRED/FAILED_PRECONDITION (422) for a precondition (e.g. KYC, terms); INVALID_ARGUMENT (400) for ids that are not UUIDs or a malformed idempotency key; KEY_IN_USE (409) with the same key still being processed; PAYLOAD_MISMATCH (422) if the key was already used with another body; VALIDATION_ERROR if the response comes outside the format (the entry may have happened: check listParticipations); UNAUTHENTICATED without a session.
redeemPromoCode()
redeemPromoCode(
input,options?):Promise<CampaignParticipation>
Redeems a promo code: joins the code's campaign. Idempotent (the gateway requires the key): repeat with the same idempotencyKey so as not to redeem twice. The response is always validated in strict mode. The code goes only in the body.
Parameters
input
code
string
termsAcceptance?
options?
Returns
Promise<CampaignParticipation>
Example
const participation = await igaming.bonus.redeemPromoCode(
{ code: 'BEMVINDO', termsAcceptance: { locale: 'pt-BR', termsRevision: localizedContent.termsRevision } },
{ idempotencyKey: key },
)Throws
BONUS_NOT_FOUND (404) for a nonexistent code; BONUS_ALREADY_CLAIMED (409) if the player already used the code; BONUS_EXPIRED/BONUS_NOT_ELIGIBLE (HTTP 500 on the gateway: identify by the code); KYC_REQUIRED/FAILED_PRECONDITION (422); RESOURCE_EXHAUSTED (429) due to the per-player promo code attempt limit, the same as resolvePromoCode (see e.retryAfter); UNAVAILABLE (503) if the gateway's limiter is down (the route fails closed for safety); INVALID_ARGUMENT (400) for a malformed idempotency key; VALIDATION_ERROR if the response comes outside the format (the redemption may have happened: check listParticipations); UNAUTHENTICATED without a session.
resolvePromoCode()
resolvePromoCode(
input,options?):Promise<PromoCodeOffer>
Shows the offer of a promo code before redemption (name, description and terms in the requested language). It does not join the campaign. The code is a secret: it goes only in the body, never in the URL or the hooks.
Parameters
input
code
string
locale
string
options?
Returns
Promise<PromoCodeOffer>
Example
const { offer, localizedContent } = await igaming.bonus.resolvePromoCode({ code: input.value, locale: 'pt-BR' })Throws
BONUS_NOT_FOUND (404) for a nonexistent or inactive code; BONUS_EXPIRED/BONUS_NOT_ELIGIBLE (HTTP 500 on the gateway: identify by the code); RESOURCE_EXHAUSTED (429) due to the attempt limit (see e.retryAfter); UNAVAILABLE (503) if the gateway's limiter is down (the route fails closed for safety); UNAUTHENTICATED without a session.