​

Loyalty program setup

​

1. Mental model

• Earn rules — named event patterns that grant points: a flat grant per event (perEvent), or a per-unit multiplier on an event property like an order total (perUnit).
• Tiers — an ordered ladder (Bronze → Platinum) keyed on a contact’s lifetime earned points. Redemptions never lower lifetime points, so climbing a tier is one-way.
• Balance — the spendable remainder, recomputed on demand from the full event history minus redemptions and operator adjustments.
• Redemption — spending points routes through the Incentives fulfillment engine, the same primitive behind referrals and surveys.

​

2. Prerequisites

• CDP events flowing. Points accrue from events in your workspace. If you have not wired event ingestion, start with the CDP API reference; the event names you send (account.created, order-completed, review.submitted, …) are the names earn rules match on.
• An API key with contacts:read for reads, contacts:write for writes. The dashboard Loyalty page is role-gated to owner and admin.
• A notion of your rewards economics. Tiers and earn rates are free, but redemption pays out real value (a code, a gift card, a custom perk) through your own fulfillment — budget earn rates against the rewards you plan to honor.

​

Supported earn-rule shapes

​

3. Configure earn rules

curl -X PUT https://api.orbit.devotel.io/api/v1/loyalty/program \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -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" },
      { "id": "review", "label": "Review bonus", "type": "perEvent", "eventName": "review.submitted", "points": 50 }
    ],
    "tiers": [
      { "id": "member", "name": "Member", "threshold": 0, "benefits": ["Earn points"] },
      { "id": "vip", "name": "VIP", "threshold": 1000, "benefits": ["2x points", "Free shipping"] }
    ],
    "pointsExpiryDays": 365
  }'

​

4. Tiers and thresholds

• Always anchor one tier at threshold 0 so the ladder has a base. Without it the program is rejected.
• Threshold is lifetime-earned, not current balance. A member who earned 5,000 points and burned 4,800 is still tier Gold.
• Benefits copy is operator-authored — a display string on the member’s profile and on their wallet card.

​

5. Preview before it ships

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/preview \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "eventName": "account.created" },
      { "eventName": "order-completed", "properties": { "total": 189.95 } }
    ]
  }'

​

6. Redeem points through incentives

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

• Concurrency-safe debit. Concurrent redemptions against the same contact serialise, so a double-click never overspends a shared balance. An attempt that exceeds the available balance returns 409 INSUFFICIENT_POINTS.
• Operator adjustment path. POST /api/v1/loyalty/members/{contactId}/adjust credits or debits points directly — useful for customer-service gestures. A debit adjustment uses the same overspend-safe path as redemption; a credit grants points without a matching event.

​

7. Carry the card in Apple and Google Wallet

​

8. Work the dashboard

• Program card shows the active program’s name, earn rules, tiers with their benefits, and the points expiry window. A tenant on the built-in default sees a Customize program button; once a custom program exists, the same button reads Edit program. Resetting to the default from the danger zone replaces your earn rules and tiers but leaves member balances untouched.
• Members panel lists contacts with any loyalty activity, each with its computed balance and tier. The panel fetches its own query, so a program-card outage never hides the member list.
• Program / Redeem / Adjust dialogs are the write surfaces: the program dialog edits earn rules and tiers; Redeem points and Adjust points act on the selected member.

​

9. Analytics and fraud guardrails

• Serialised debits. Redemptions and debit adjustments on one contact run through a per-contact lock, so concurrent spend on a shared (family or business) balance cannot overspend it. A reward draw bigger than the available balance gets a structured 409 INSUFFICIENT_POINTS instead of a partial debit.
• Event-sourced incentives. Every payout leaves an audit-grade record in the incentives ledger, filterable by source, reward_type, and contact_id. An unusual redemption velocity by one contact shows up there, not as a silent drain.

​

10. Related reading

• Loyalty API reference — per-endpoint schemas and response envelopes.
• CDP API — the event stream points accrue from.
• CDP event model — how events are shaped and ingested.
• Incentives — the reward engine redemptions route through.
• Issue and deliver a wallet pass end to end — carry the member card on a phone.
• Segments — use loyalty traits (loyalty_points_balance, loyalty_tier, …) as entry conditions.