Rewards
getRewards, hasReward, and claimReward — reading and claiming the current user's reward ledger
The SDK reads the current user's reward ledger — the same records the reward webhook delivers and the dashboard shows. One source of truth, two consumption styles: pull-based reads here, or push via the webhook.
Grant anything valuable — free access, currency, unlocks — from your server via the signed reward webhook. Client-side reads and claims are for display and low-stakes grants: a compromised client can lie to itself. On mobile, keep reward flows framed as product benefit — never cash-for-install, which app review rejects.
getRewards
The current user's full reward ledger, optionally filtered.
| Parameter | Type | Description |
|---|---|---|
filter.status | RewardStatus | Optional. pending, available, claimed, fulfilled, or expired. |
filter.campaignId | string | Optional. Limit to one campaign. |
filter.kind | string | Optional. Limit to a reward kind, e.g. free_month. |
Returns a list of Reward records — { id, kind, status, campaignId, title, payload, createdAt, claimedAt }, with title display-ready.
invitebase.getRewards(filter?: RewardFilter): Promise<Reward[]>const rewards = await invitebase.getRewards({ status: 'available' });
rewardsList.render(rewards);Invitebase.getRewards(filter: RewardFilter? = nil) async throws -> [Reward]let available = try await Invitebase.getRewards(filter: .init(status: .available))suspend fun Invitebase.getRewards(filter: RewardFilter? = null): List<Reward>val available = Invitebase.getRewards(RewardFilter(status = RewardStatus.AVAILABLE))getRewards(filter?: RewardFilter): Promise<Reward[]>In components, prefer the useRewards hook — it re-renders the moment a reward is earned, fulfilled, or claimed:
const { rewards, refresh } = useRewards({ status: 'available' });static Future<List<Reward>> Invitebase.getRewards({RewardFilter? filter})final available = await Invitebase.getRewards(
filter: RewardFilter(status: RewardStatus.available),
);hasReward
Render-time availability check for one reward — cheaper and clearer than filtering the full ledger.
| Parameter | Type | Description |
|---|---|---|
kindOrId | string | A reward kind (super_referrer_badge) or reward ID (8f3a2b1c-6d94-4e07-9a58-1b7c4d2e9f30). |
Returns true if the user has this reward available and unclaimed.
invitebase.hasReward(kindOrId: string): Promise<boolean>if (await invitebase.hasReward('super_referrer_badge')) {
profileBadge.show();
}Invitebase.hasReward(_ kindOrId: String) async throws -> Boolif try await Invitebase.hasReward("super_referrer_badge") {
profileView.showBadge()
}suspend fun Invitebase.hasReward(kindOrId: String): Booleanif (Invitebase.hasReward("super_referrer_badge")) {
profileState.showBadge = true
}hasReward(kindOrId: string): Promise<boolean>const invitebase = useInvitebase();
const hasBadge = await invitebase.hasReward('super_referrer_badge');static Future<bool> Invitebase.hasReward(String kindOrId)if (await Invitebase.hasReward('super_referrer_badge')) {
showProfileBadge();
}claimReward
Claims a client-granted reward, exactly once. Claims are recorded server-side and transition the reward available → claimed; a second claim throws, so you can grant from the client without double-granting.
| Parameter | Type | Description |
|---|---|---|
rewardId | string | The reward to claim. |
Returns the updated Reward with status: claimed.
invitebase.claimReward(rewardId: string): Promise<Reward>const reward = await invitebase.claimReward('8f3a2b1c-6d94-4e07-9a58-1b7c4d2e9f30');
unlockFeature(reward.kind);Invitebase.claimReward(_ rewardId: String) async throws -> Rewardlet reward = try await Invitebase.claimReward("8f3a2b1c-6d94-4e07-9a58-1b7c4d2e9f30")
entitlements.unlock(reward.kind)suspend fun Invitebase.claimReward(rewardId: String): Rewardval reward = Invitebase.claimReward("8f3a2b1c-6d94-4e07-9a58-1b7c4d2e9f30")
entitlements.unlock(reward.kind)claimReward(rewardId: string): Promise<Reward>const invitebase = useInvitebase();
await invitebase.claimReward(item.id);static Future<Reward> Invitebase.claimReward(String rewardId)final reward = await Invitebase.claimReward('8f3a2b1c-6d94-4e07-9a58-1b7c4d2e9f30');
entitlements.unlock(reward.kind);