---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk-igaming/interfaces/BonusApi.md
---
[Reference](../../../index.md) / [@getenginex/sdk-igaming](../index.md) / BonusApi

# BonusApi

Bonus campaigns and promo codes. Only `listPublicOffers` is public; the other methods require login.

## Methods

### claim()

> **claim**(`input`, `options?`): `Promise`<[`CampaignParticipation`](CampaignParticipation.md)>

Redeems the reward of a qualified participation (campaigns with `player_claim`).
**Idempotent**, like [BonusApi.optIn](#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?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CampaignParticipation`](CampaignParticipation.md)>

#### Example

```ts
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`](CampaignOffer.md)>

An offer available to the player.

#### Parameters

##### input

###### campaignId

`string`

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CampaignOffer`](CampaignOffer.md)>

#### Example

```ts
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`](CampaignParticipation.md)>

One of the player's participations.

#### Parameters

##### input

###### participationId

`string`

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CampaignParticipation`](CampaignParticipation.md)>

#### Example

```ts
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`](../../sdk/interfaces/CursorPage.md)<[`CampaignOffer`](CampaignOffer.md)>>

Offers available to the logged-in player. Cursor-paginated.

#### Parameters

##### input?

[`CursorPageInput`](../../sdk/interfaces/CursorPageInput.md)

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CursorPage`](../../sdk/interfaces/CursorPage.md)<[`CampaignOffer`](CampaignOffer.md)>>

#### Example

```ts
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`](../../sdk/interfaces/CursorPage.md)<[`CampaignParticipation`](CampaignParticipation.md)>>

The player's participations. Cursor-paginated.

#### Parameters

##### input?

[`CursorPageInput`](../../sdk/interfaces/CursorPageInput.md)

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CursorPage`](../../sdk/interfaces/CursorPage.md)<[`CampaignParticipation`](CampaignParticipation.md)>>

#### Example

```ts
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`](../../sdk/interfaces/CursorPage.md)<[`CampaignOffer`](CampaignOffer.md)>>

Public catalog of offers (storefront, no login): it only describes the campaigns; eligibility,
joining and participations require login. Cursor-paginated.

#### Parameters

##### input?

[`CursorPageInput`](../../sdk/interfaces/CursorPageInput.md)

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CursorPage`](../../sdk/interfaces/CursorPage.md)<[`CampaignOffer`](CampaignOffer.md)>>

#### Example

```ts
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`](CampaignParticipation.md)>

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

[`OptInInput`](OptInInput.md)

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CampaignParticipation`](CampaignParticipation.md)>

#### Example

```ts
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`](CampaignParticipation.md)>

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?

[`CampaignTermsAcceptance`](CampaignTermsAcceptance.md)

##### options?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`CampaignParticipation`](CampaignParticipation.md)>

#### Example

```ts
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`](PromoCodeOffer.md)>

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?

[`CallOptions`](../../sdk/interfaces/CallOptions.md)

#### Returns

`Promise`<[`PromoCodeOffer`](PromoCodeOffer.md)>

#### Example

```ts
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.
