{
  "data": {
    "program": {
      "id": "loy_prog_01",
      "name": "VIP Rewards",
      "earnRules": [
        { "id": "signup", "label": "Sign-up bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
        { "id": "spend", "label": "$1 = 1 point", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
      ],
      "tiers": [
        { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
        { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] }
      ],
      "pointsExpiryDays": 365
    },
    "program_source": "custom",
    "revision_id": "cdp_evt_01J8QWXYZ",
    "redemption_event_name": "loyalty.points_redeemed",
    "relevant_event_names": ["loyalty.points_redeemed", "loyalty.points_adjusted", "account.created", "order-completed"]
  },
  "meta": { "request_id": "req_01J8QWXYZ", "timestamp": "2026-08-26T10:00:00Z" }
}

Loyalty API

Loyalty is a points-and-tiers rewards program computed on top of the events you’re already sending to the Customer Data Platform — there’s no separate ledger table to sync. Points accrue from a contact’s behavioral CDP events per rules you define (e.g. 100 pts for account.created, 1 pt per $1 of order-completed), points burn through redemptions, and a contact’s balance + tier are recomputed on demand from that event history. Base path: /api/v1/loyalty Authentication: API key (X-API-Key) or session JWT. Reads require contacts:read; writes require contacts:write.

Method	Path	Purpose
`GET`	`/api/v1/loyalty/program`	Get the active program config
`POST`	`/api/v1/loyalty/program`	Create / replace the program config (201)
`PUT`	`/api/v1/loyalty/program`	Update the active program config
`DELETE`	`/api/v1/loyalty/program`	Reset to the default program (204, empty body)
`POST`	`/api/v1/loyalty/preview`	Simulate a program against sample events (no DB write)
`GET`	`/api/v1/loyalty/members`	Paginated list of contacts with loyalty activity
`GET`	`/api/v1/loyalty/members/{contactId}`	One contact’s balance, tier, and traits
`POST`	`/api/v1/loyalty/members/{contactId}/redeem`	Debit points (a redemption)
`POST`	`/api/v1/loyalty/members/{contactId}/adjust`	Operator credit or debit adjustment

Program config

A program has earn rules and tiers:

perEvent rule — a flat point grant every time a named event fires (e.g. 50 points on review.submitted).
perUnit rule — points = value_in_event_property × pointsPerUnit, rounded per the rule’s rounding mode (e.g. 1 point per $1 of an order’s total).
Tiers — an ordered ladder (Bronze → Platinum), each with a lifetime-points threshold and operator-authored benefits copy. The base tier’s threshold is 0 so every contact always has a current tier.
pointsExpiryDays — optional; when set, points lapse this many days after they’re earned. Omit for points that never expire.

A tenant that hasn’t configured its own program still gets a sensible default: a welcome bonus, points-per-dollar-spent, a review bonus, and a four-tier Bronze→Platinum ladder with a 365-day expiry.

curl -X PUT https://api.orbit.devotel.io/api/v1/loyalty/program \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Rewards",
    "earnRules": [
      { "id": "signup", "label": "Sign-up bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
      { "id": "spend", "label": "$1 = 1 point", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
    ],
    "tiers": [
      { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
      { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] }
    ],
    "pointsExpiryDays": 365
  }'

Node

// The Node SDK is not published to a registry yet — use dependency-free fetch (Node 18+).
const res = await fetch('https://api.orbit.devotel.io/api/v1/loyalty/program', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'VIP Rewards',
    earnRules: [
      { id: 'signup', label: 'Sign-up bonus', type: 'perEvent', eventName: 'account.created', points: 100 },
      { id: 'spend', label: '$1 = 1 point', type: 'perUnit', eventName: 'order-completed', field: 'total', pointsPerUnit: 1, rounding: 'floor' },
    ],
    tiers: [
      { id: 'member', name: 'Member', threshold: 0, benefits: ['1x points'] },
      { id: 'vip', name: 'VIP', threshold: 1000, benefits: ['2x points', 'Free shipping'] },
    ],
    pointsExpiryDays: 365,
  }),
});
console.log(await res.json());

{
  "data": {
    "program": {
      "id": "loy_prog_01",
      "name": "VIP Rewards",
      "earnRules": [
        { "id": "signup", "label": "Sign-up bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
        { "id": "spend", "label": "$1 = 1 point", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
      ],
      "tiers": [
        { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
        { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] }
      ],
      "pointsExpiryDays": 365
    },
    "program_source": "custom",
    "revision_id": "cdp_evt_01J8QWXYZ",
    "redemption_event_name": "loyalty.points_redeemed",
    "relevant_event_names": ["loyalty.points_redeemed", "loyalty.points_adjusted", "account.created", "order-completed"]
  },
  "meta": { "request_id": "req_01J8QWXYZ", "timestamp": "2026-08-26T10:00:00Z" }
}

POST /program (create) and GET /program return this same envelope — create responds 201, read includes program_source: "default" until you author a program. DELETE /program resets to the default and responds 204 with an empty body (the points ledger is untouched — only the config reverts).

Preview before you commit

POST /preview runs the accrual/tier engine against sample events you supply — either your current program or an override — with no database write. Use it to tune earn rules and tier thresholds before adopting them.

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/preview \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_name": "order-completed", "properties": { "total": 250 } },
      { "event_name": "order-completed", "properties": { "total": 90 } }
    ]
  }'

Node

const res = await fetch('https://api.orbit.devotel.io/api/v1/loyalty/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      { event_name: 'order-completed', properties: { total: 250 } },
      { event_name: 'order-completed', properties: { total: 90 } },
    ],
  }),
});
console.log(await res.json());

Omit program to run against your saved (or default) program; send program to evaluate a candidate override. Either way the response projects the balance and tier those events would produce for one contact:

{
  "data": {
    "program_source": "default",
    "state": {
      "program": "Orbit Rewards",
      "balance": {
        "available": 340,
        "lifetimeEarned": 340,
        "totalRedeemed": 0,
        "expired": 0,
        "expiringSoon": 340,
        "nextExpiryAt": "2027-08-26T10:00:00Z"
      },
      "tier": {
        "current": { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
        "next": { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] },
        "pointsToNext": 660,
        "progress": 0.34
      },
      "traits": {
        "loyalty_points_balance": 340,
        "loyalty_lifetime_points": 340,
        "loyalty_tier": "Member",
        "loyalty_tier_id": "member"
      }
    }
  },
  "meta": { "request_id": "req_01J8QX012", "timestamp": "2026-08-26T10:00:00Z" }
}

Members, balance, and redemption

GET /members lists every contact with loyalty activity, each with a computed balance and tier. Pages use limit (1–100, default 25) and offset as documented in Pagination — the members list is one of the offset-based endpoint families.

curl "https://api.orbit.devotel.io/api/v1/loyalty/members?limit=2&offset=0" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node

const res = await fetch('https://api.orbit.devotel.io/api/v1/loyalty/members?limit=2&offset=0', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY },
});
console.log(await res.json());

{
  "data": {
    "members": [
      {
        "contact_id": "cnt_abc123",
        "event_count": 14,
        "last_activity_at": "2026-08-20T14:12:00Z",
        "balance": {
          "available": 340,
          "lifetimeEarned": 840,
          "totalRedeemed": 500,
          "expired": 0,
          "expiringSoon": 120,
          "nextExpiryAt": "2026-09-15T00:00:00Z"
        },
        "tier": {
          "current": { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
          "next": { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] },
          "pointsToNext": 160,
          "progress": 0.84
        },
        "traits": {
          "loyalty_points_balance": 340,
          "loyalty_lifetime_points": 840,
          "loyalty_tier": "Member",
          "loyalty_tier_id": "member"
        }
      }
    ],
    "program_name": "VIP Rewards",
    "limit": 2,
    "offset": 0
  },
  "meta": { "request_id": "req_01J8QY345", "timestamp": "2026-08-26T10:00:00Z" }
}

GET /members/{contactId} returns one contact’s full state — available points, lifetimeEarned (drives tier; redemptions never lower it), expiringSoon, and nextExpiryAt.

curl https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node

const contactId = 'cnt_abc123';
const res = await fetch(`https://api.orbit.devotel.io/api/v1/loyalty/members/${contactId}`, {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY },
});
console.log(await res.json());

{
  "data": {
    "contact_id": "cnt_abc123",
    "program": "VIP Rewards",
    "balance": {
      "available": 340,
      "lifetimeEarned": 840,
      "totalRedeemed": 500,
      "expired": 0,
      "expiringSoon": 120,
      "nextExpiryAt": "2026-09-15T00:00:00Z"
    },
    "tier": {
      "current": { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
      "next": { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] },
      "pointsToNext": 160,
      "progress": 0.84
    },
    "traits": {
      "loyalty_points_balance": 340,
      "loyalty_lifetime_points": 840,
      "loyalty_tier": "Member",
      "loyalty_tier_id": "member"
    }
  },
  "meta": { "request_id": "req_01J8QZ678", "timestamp": "2026-08-26T10:00:00Z" }
}

POST /members/{contactId}/redeem atomically debits points — concurrent redemptions against the same contact can’t overspend a shared balance. It returns 409 INSUFFICIENT_POINTS when the requested amount exceeds the available balance.

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_abc123/redeem \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "points": 500, "reward": "10% off coupon", "reference": "ord_9182" }'

Node

const res = await fetch('https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_abc123/redeem', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ points: 500, reward: '10% off coupon', reference: 'ord_9182' }),
});
console.log(await res.json());

A successful redemption responds 201 with the post-debit state:

{
  "data": {
    "contact_id": "cnt_abc123",
    "redemption_event_id": "cdp_evt_01J8R0ABC",
    "debited": 500,
    "program": "VIP Rewards",
    "balance": {
      "available": 340,
      "lifetimeEarned": 840,
      "totalRedeemed": 500,
      "expired": 0,
      "expiringSoon": 120,
      "nextExpiryAt": "2026-09-15T00:00:00Z"
    },
    "tier": {
      "current": { "id": "member", "name": "Member", "threshold": 0, "benefits": ["1x points"] },
      "next": { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] },
      "pointsToNext": 160,
      "progress": 0.84
    },
    "traits": {
      "loyalty_points_balance": 340,
      "loyalty_lifetime_points": 840,
      "loyalty_tier": "Member",
      "loyalty_tier_id": "member"
    }
  },
  "meta": { "request_id": "req_01J8R1DEF", "timestamp": "2026-08-26T10:00:00Z" }
}

When the requested amount exceeds the balance, the error body names both figures so you can surface them to the customer:

{
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Insufficient points: available 340, requested 500.",
    "status": 409
  },
  "meta": { "request_id": "req_01J8R2GHI", "timestamp": "2026-08-26T10:00:00Z" }
}

POST /members/{contactId}/adjust is the operator override: {"direction": "credit", "points": 200, "reason": "Customer service gesture"} grants points directly; {"direction": "debit", ...} removes them through the same overspend-safe path as redemption. Credit:

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_abc123/adjust \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "credit", "points": 200, "reason": "Customer service gesture" }'

Node

const res = await fetch('https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_abc123/adjust', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ direction: 'credit', points: 200, reason: 'Customer service gesture' }),
});
console.log(await res.json());

{
  "data": {
    "contact_id": "cnt_abc123",
    "adjustment_event_id": "cdp_evt_01J8R3JKL",
    "direction": "credit",
    "points": 200,
    "program": "VIP Rewards",
    "balance": {
      "available": 540,
      "lifetimeEarned": 1040,
      "totalRedeemed": 500,
      "expired": 0,
      "expiringSoon": 120,
      "nextExpiryAt": "2026-09-15T00:00:00Z"
    },
    "tier": {
      "current": { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] },
      "next": null,
      "pointsToNext": 0,
      "progress": 1
    },
    "traits": {
      "loyalty_points_balance": 540,
      "loyalty_lifetime_points": 1040,
      "loyalty_tier": "VIP",
      "loyalty_tier_id": "vip"
    }
  },
  "meta": { "request_id": "req_01J8R4MNO", "timestamp": "2026-08-26T10:00:00Z" }
}

Debit: send "direction": "debit" with the same points / reason / reference fields. A debit responds 201 with direction: "debit", the deducted points, and the post-debit state; it returns the same 409 INSUFFICIENT_POINTS envelope as redeem when the balance can’t cover the deduction.

Segments and journeys

Every member’s computed state is exposed as traits — loyalty_points_balance, loyalty_lifetime_points, loyalty_tier, loyalty_tier_id — usable directly as entry conditions in Segments and flow triggers, e.g. loyalty_points_balance >= 500.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Loyalty API: points, tiers, and redemption endpoints

Loyalty API

Program config

Preview before you commit

Members, balance, and redemption

Segments and journeys

See also

​Loyalty API

​Program config

​Preview before you commit

​Members, balance, and redemption

​Segments and journeys

​See also

Loyalty API

Program config

Preview before you commit

Members, balance, and redemption

Segments and journeys

See also