Tiers

Tiers classify members by lifetime engagement and unlock escalating benefits. As a member accumulates lifetimePoints, they advance through tiers automatically — no manual promotion needed.

How tiers work

Define tiers with a minLifetimePoints threshold each — e.g. Bronze = 0, Silver = 1 000, Gold = 5 000.
Every evaluate() call accrues lifetimePoints on the member. Unlike the spendable balance, lifetime points never decrease on redemption.
When a member crosses a threshold, their tier updates and the member.tier_changed webhook fires.
Each tier's benefits define what the member unlocks.

Benefit types

EARN_MULTIPLIER

Members earn this multiple of the base points rate. The multiplier is applied during evaluate() — a 1.5× Gold member earns 150 points where a Bronze member earns 100.

LABEL

A text perk shown in member-facing UIs ("Free delivery", "Priority support"). No engine behaviour.

EXCLUSIVE_CAMPAIGN

Restricts a campaign so only members at this tier (or higher) can earn from it.

FREE_REWARD

A tangible reward unlocked at this tier — coupon, gift card, free item, or discount voucher.

Applying the earn multiplier

The engine surfaces the member's active EARN_MULTIPLIER so points scale automatically with tier. You don't apply it yourself — read the member's current tier from the member record or the member.tier_changed webhook to drive your own UI.

Create a tier

cURL

curl -X POST ".../tenants/$TENANT_ID/tiers" \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":              "Gold",
    "minLifetimePoints": 5000,
    "sortOrder":         3,
    "benefits": [
      { "type": "EARN_MULTIPLIER", "multiplier": 1.5 },
      { "type": "LABEL", "description": "Priority support" }
    ]
  }'

Full field definitions and all endpoints are in the Tiers API reference.