Tiers

Loyalty tiers are lifetime-points thresholds that classify members. When a member's lifetimePoints crosses a tier threshold, they advance automatically and the member.tier_changed webhook fires.

How it works

1. Create tiers with minLifetimePoints thresholds (e.g. Bronze = 0 pts, Silver = 1 000 pts, Gold = 5 000 pts).
2. Every evaluate() call accumulates lifetimePoints on the member.
3. When a threshold is crossed, the member's tier updates automatically and a member.tier_changed webhook fires.
4. Add benefits (EARN_MULTIPLIER, LABEL, EXCLUSIVE_CAMPAIGN) to define what members unlock at each tier.

Endpoints

GET

/tenants/{tenantId}/tiers

List all tiers ordered by sortOrder ascending.

POST

/tenants/{tenantId}/tiers

Create a tier. Set minLifetimePoints as the entry threshold. Add benefits to define perks.

PATCH

/tenants/{tenantId}/tiers/{tierId}

Update tier name, minLifetimePoints, benefits, badgeUrl, or sortOrder.

DELETE

/tenants/{tenantId}/tiers/{tierId}

Delete a tier. Returns 409 if members currently hold it. Pass ?force=true to override.

Tier Fields

namestringDisplay name (e.g. "Gold", "Platinum").

minLifetimePointsintegerMinimum lifetime points a member must accumulate to enter this tier.

benefitsarrayPerks unlocked at this tier. Each item is a discriminated union: EARN_MULTIPLIER | LABEL | EXCLUSIVE_CAMPAIGN | FREE_REWARD.

sortOrderintegerDisplay order. Tiers are returned sorted by sortOrder ascending.

badgeUrlstringOptional URL to a badge image shown on member-facing UIs. Nullable.

Benefit Types

EARN_MULTIPLIERmultiplier: number

Members at this tier earn this multiple of the base points rate. Apply in your checkout logic using the multiplier value.

LABELdescription: string

A text perk shown in the member UI (e.g. "Priority support", "Free delivery").

EXCLUSIVE_CAMPAIGNcampaignId: string (uuid)

Only members at this tier (or higher) can earn from the specified campaign.

FREE_REWARDrewardType: string, value: object

A free reward unlocked at this tier. Shape of value depends on your reward catalogue.

Create a tier

cURL

curl -X POST "https://loyalty-engine-production-e5cb.up.railway.app/v1/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" }
    ]
  }'

List tiers

200 OK

{
  "tiers": [
    {
      "id":                "tier-uuid-1",
      "tenantId":          "tenant-uuid",
      "name":              "Bronze",
      "minLifetimePoints": 0,
      "benefits":          [],
      "badgeUrl":          null,
      "sortOrder":         1,
      "createdAt":         "2026-01-01T00:00:00.000Z",
      "updatedAt":         "2026-01-01T00:00:00.000Z"
    },
    {
      "id":                "tier-uuid-2",
      "tenantId":          "tenant-uuid",
      "name":              "Silver",
      "minLifetimePoints": 1000,
      "benefits":          [{ "type": "EARN_MULTIPLIER", "multiplier": 1.25 }],
      "badgeUrl":          null,
      "sortOrder":         2,
      "createdAt":         "2026-01-01T00:00:00.000Z",
      "updatedAt":         "2026-01-01T00:00:00.000Z"
    },
    {
      "id":                "tier-uuid-3",
      "tenantId":          "tenant-uuid",
      "name":              "Gold",
      "minLifetimePoints": 5000,
      "benefits":          [{ "type": "EARN_MULTIPLIER", "multiplier": 1.5 }],
      "badgeUrl":          null,
      "sortOrder":         3,
      "createdAt":         "2026-01-01T00:00:00.000Z",
      "updatedAt":         "2026-01-01T00:00:00.000Z"
    }
  ]
}