Guide · Entitlements

Phase two

Keep the rule flexible and the product key stable.

An entitlement is Our Impact’s evaluated answer about one supporter. Your application chooses what that answer unlocks.

Design the contract between teams

Program owner

Defines who qualifies

A program or community team can say “donate at least $50” or “complete three donations this month.”

Software team

Defines what the key does

Code reacts to community_champion_theme without duplicating qualification logic.

Understand the entitlement shape

entitlement.json
{
  "entitlement_key": "community_champion_theme",
  "state": "active",
  "qualifying_count": 1,
  "progress_value": 1,
  "progress_unit": "events",
  "qualified_at": "2026-11-06T12:00:01Z",
  "valid_until": null,
  "updated_at": "2026-11-06T12:00:01Z"
}
state
Current active/inactive answer.
qualifying_count
Records that matched the rule window.
progress_value
Count, or accumulated minor currency units.
progress_unit
events, or a lowercase ISO currency code. For example, 5000 plus usd means $50.00.
qualified_at
When the supporter most recently qualified.
valid_until
Optional expiry; null means no fixed expiration.

Use the browser helper

The preview browser package caches one entitlement request and checks expiry when you call user.is().

community-access.ts
import { OurImpact } from "@our-impact/browser";

const impact = new OurImpact({
  publishableKey: "oi_pk_test_...",
  userToken,
});

const hasTheme = await impact.user.is("community_champion_theme");
const allAccess = await impact.user.all();

if (hasTheme) {
  document.documentElement.dataset.theme = "community-champion";
}

Choose the read that matches the decision

user.is(key)Client feature toggles
Returns a boolean and accounts for state and expiry. Use it for themes, badges, and immediate UI changes.
user.get(key)Client progress UI
Returns one full entitlement or null, including qualification count, progress, and validity.
user.all()Client dashboards
Returns all evaluated entitlements from the browser SDK’s shared cached request.
user.profile()Client identity display
Returns the identified supporter profile associated with the current token.
listUserEntitlements()Server authorization
Reads one supporter using the project secret and stable external user ID.

Enforce sensitive access on the server

A browser entitlement is excellent for presentation, but it must not be the only check protecting paid data, private routes, or privileged mutations.

lib/our-impact/access.ts
import { OurImpactClient } from "@our-impact/node";

const ourImpact = new OurImpactClient({
  secretApiKey: process.env.OUR_IMPACT_SECRET_KEY,
});

const state = await ourImpact.entitlements.listUserEntitlements({
  externalUserId: "storefront:user_01JABC",
});

const hasServerAccess = state.entitlements.some(
  (item) =>
    item.entitlementKey === "community_champion_theme" &&
    item.state === "active" &&
    (!item.validUntil || item.validUntil > new Date()),
);

Good entitlement keys

  • Use product language: community_champion_theme, supporter_badge, or tier_3.
  • Do not encode thresholds into names such as donated_50_dollars; thresholds will change.
  • Treat renaming a key as an API-breaking change for the applications using it.