Loyalty worked sequences and errors

curl "https://api.orbit.devotel.io/api/v1/loyalty/program" \
  -H "X-API-Key: <your-api-key>"

{
  "data": {
    "program": {
      "name": "Rewards",
      "earnRules": [
        { "id": "welcome", "label": "Welcome bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
        { "id": "purchase-value", "label": "Points per $1 spent", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
      ],
      "tiers": [
        { "id": "bronze", "name": "Bronze", "threshold": 0, "benefits": ["Earn 1 point per $1"] },
        { "id": "silver", "name": "Silver", "threshold": 500, "benefits": ["Free shipping", "Early sale access"] },
        { "id": "gold", "name": "Gold", "threshold": 2000, "benefits": ["Free shipping", "2x points events", "Priority support"] }
      ],
      "pointsExpiryDays": 365
    },
    "program_source": "default",
    "redemption_event_name": "loyalty.points_redeemed",
    "relevant_event_names": ["loyalty.points_redeemed", "loyalty.points_adjusted", "account.created", "order-completed"]
  },
  "meta": {
    "request_id": "req_loyalty_prog",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

curl "https://api.orbit.devotel.io/api/v1/loyalty/program" \
  -H "X-API-Key: <your-api-key>"

{
  "data": {
    "program": {
      "name": "Rewards",
      "earnRules": [
        { "id": "welcome", "label": "Welcome bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
        { "id": "purchase-value", "label": "Points per $1 spent", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
      ],
      "tiers": [
        { "id": "bronze", "name": "Bronze", "threshold": 0, "benefits": ["Earn 1 point per $1"] },
        { "id": "silver", "name": "Silver", "threshold": 500, "benefits": ["Free shipping", "Early sale access"] },
        { "id": "gold", "name": "Gold", "threshold": 2000, "benefits": ["Free shipping", "2x points events", "Priority support"] }
      ],
      "pointsExpiryDays": 365
    },
    "program_source": "default",
    "redemption_event_name": "loyalty.points_redeemed",
    "relevant_event_names": ["loyalty.points_redeemed", "loyalty.points_adjusted", "account.created", "order-completed"]
  },
  "meta": {
    "request_id": "req_loyalty_prog",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Worked request and response samples

The chain every loyalty integration walks: read the tenant’s active program, enroll a member by accrual, read the balance back, preview a redemption, burn points, and page the ledger. Every block is a full envelope as the API returns it — copy the request, substitute your own contact id, and compare the { data, meta } shape.

1. Read the active loyalty program

GET /api/v1/loyalty/program

Fetch the active program — its earn rules, tiers, and points-expiry window — before enrolling anyone so you can render the ladder. program_source is "default" until a tenant authors its own program with POST /api/v1/loyalty/program (then "custom"); burn behaviour is fixed (FIFO, oldest lot first) and the redemption amounts are per request — see step 4. Request

curl "https://api.orbit.devotel.io/api/v1/loyalty/program" \
  -H "X-API-Key: <your-api-key>"

{
  "data": {
    "program": {
      "name": "Rewards",
      "earnRules": [
        { "id": "welcome", "label": "Welcome bonus", "type": "perEvent", "eventName": "account.created", "points": 100 },
        { "id": "purchase-value", "label": "Points per $1 spent", "type": "perUnit", "eventName": "order-completed", "field": "total", "pointsPerUnit": 1, "rounding": "floor" }
      ],
      "tiers": [
        { "id": "bronze", "name": "Bronze", "threshold": 0, "benefits": ["Earn 1 point per $1"] },
        { "id": "silver", "name": "Silver", "threshold": 500, "benefits": ["Free shipping", "Early sale access"] },
        { "id": "gold", "name": "Gold", "threshold": 2000, "benefits": ["Free shipping", "2x points events", "Priority support"] }
      ],
      "pointsExpiryDays": 365
    },
    "program_source": "default",
    "redemption_event_name": "loyalty.points_redeemed",
    "relevant_event_names": ["loyalty.points_redeemed", "loyalty.points_adjusted", "account.created", "order-completed"]
  },
  "meta": {
    "request_id": "req_loyalty_prog",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

2. Enroll a member — send their first behavioural event

POST /api/v1/track (CDP endpoint)

There is no enroll call — a contact enrolls when you track an event that matches an earn rule. Send the tenant’s real CDP track endpoint with the contact id, the event name from a rule in step 1, and any rule field (total here) as properties; points accrue per the program. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
  "contact_id": "ct_3k9m2a8f1e4b6c7d",
  "type": "track",
  "event_name": "account.created",
  "properties": {}
}'

{
  "data": {
    "contact_id": "ct_3k9m2a8f1e4b6c7d",
    "event_id": "cdp_evt_8x2p9a1",
    "status": "tracked"
  },
  "meta": {
    "request_id": "req_loyalty_track",
    "timestamp": "2026-09-08T12:01:00Z"
  }
}

3. Accrue points

Points accrue from the events you already track — a purchase event referencing the order id, a campaign action — per the earn rules. Every read below projects the balance over that stream, so there is no write step to sync earned points.

Track the accrual event, then the member detail read reflects it immediately. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
  "contact_id": "ct_3k9m2a8f1e4b6c7d",
  "type": "track",
  "event_name": "order-completed",
  "properties": { "total": 250, "order_id": "ord_9z4t7q2" }
}'

Balance after the read

{
  "data": {
    "contact_id": "ct_3k9m2a8f1e4b6c7d",
    "program": "Rewards",
    "balance": {
      "available": 350,
      "lifetimeEarned": 350,
      "totalRedeemed": 0,
      "expired": 0,
      "expiringSoon": 0,
      "nextExpiryAt": "2027-09-14T12:01:00Z"
    },
    "tier": {
      "current": { "id": "bronze", "name": "Bronze", "threshold": 0 },
      "next": { "id": "silver", "threshold": 500 },
      "pointsToNext": 150,
      "progress": 0.7
    },
    "traits": {
      "loyalty_points_balance": 350,
      "loyalty_lifetime_points": 350,
      "loyalty_tier": "Bronze",
      "loyalty_tier_id": "bronze"
    }
  },
  "meta": {
    "request_id": "req_loyalty_bal",
    "timestamp": "2026-09-08T12:01:30Z"
  }
}

4. Preview a redemption (simulate)

POST /api/v1/loyalty/preview

Simulate the program against sample events before you burn — the body carries optional per-event properties (here the same purchase value and order reference the member’s real events carry), and the response data.state projects the exact balance and tier that set would produce. Pure: nothing is written, so safe to poll from a checkout page. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/loyalty/preview" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
  "events": [
    { "event_name": "account.created", "properties": {}, "occurred_at": "2026-09-01T09:00:00Z" },
    { "event_name": "order-completed", "properties": { "total": 250, "order_id": "ord_9z4t7q2" }, "occurred_at": "2026-09-14T12:01:00Z" }
  ]
}'

{
  "data": {
    "program_source": "default",
    "state": {
      "program": "Rewards",
      "balance": {
        "available": 350,
        "lifetimeEarned": 350,
        "totalRedeemed": 0,
        "expired": 0,
        "expiringSoon": 0,
        "nextExpiryAt": "2027-09-01T09:00:00Z"
      },
      "tier": {
        "current": { "id": "bronze", "name": "Bronze", "threshold": 0 },
        "next": { "id": "silver", "threshold": 500 },
        "pointsToNext": 150,
        "progress": 0.7
      },
      "traits": {
        "loyalty_points_balance": 350,
        "loyalty_lifetime_points": 350,
        "loyalty_tier": "Bronze",
        "loyalty_tier_id": "bronze"
      }
    }
  },
  "meta": {
    "request_id": "req_loyalty_prev",
    "timestamp": "2026-09-08T12:02:00Z"
  }
}

5. Burn — redeem from a member’s balance

POST /api/v1/loyalty/members/{contactId}/redeem

Burns points under a per-contact advisory lock, so two concurrent redemptions cannot both spend the same balance. reward and reference are recorded on the ledger event for reconciliation. The response spreads the post-burn state — the same balance/tier/traits shape as step 3 — plus the redemption event id. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/loyalty/members/ct_3k9m2a8f1e4b6c7d/redeem" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
  "points": 200,
  "reward": "Free shipping coupon",
  "reference": "ord_9z4t7q2"
}'

{
  "data": {
    "contact_id": "ct_3k9m2a8f1e4b6c7d",
    "redemption_event_id": "cdp_evt_7k5n2a9",
    "debited": 200,
    "balance": {
      "available": 150,
      "lifetimeEarned": 350,
      "totalRedeemed": 200,
      "expired": 0,
      "expiringSoon": 0,
      "nextExpiryAt": "2027-09-14T12:01:00Z"
    },
    "tier": {
      "current": { "id": "bronze", "name": "Bronze", "threshold": 0 },
      "next": { "id": "silver", "threshold": 500 },
      "pointsToNext": 150,
      "progress": 0.7
    }
  },
  "meta": {
    "request_id": "req_loyalty_burn",
    "timestamp": "2026-09-08T12:03:00Z"
  }
}

6. Page the member ledger

GET /api/v1/loyalty/members?limit=25&offset=0 (then the per-member GET /api/v1/loyalty/members/{contactId} for the full detail)

The members list pages by most-recent activity (limit 1–100, default 25; offset from 0). Each row carries the computed state. A redemption or a debit reversal (POST …/adjust with "direction": "debit") shows as totalRedeemed growth — and since reversal events are the adjustment/redeem rows in the same stream, event_count and last_activity_at move in step with the burn, never lowering lifetimeEarned. Request

curl "https://api.orbit.devotel.io/api/v1/loyalty/members?limit=25&offset=0" \
  -H "X-API-Key: <your-api-key>"

{
  "data": {
    "members": [
      {
        "contact_id": "ct_3k9m2a8f1e4b6c7d",
        "event_count": 3,
        "last_activity_at": "2026-09-14T12:03:00Z",
        "balance": { "available": 150, "lifetimeEarned": 350, "totalRedeemed": 200, "expired": 0 },
        "tier": { "current": { "id": "bronze", "name": "Bronze", "threshold": 0 }, "pointsToNext": 150 },
        "traits": { "loyalty_points_balance": 150, "loyalty_tier": "Bronze" }
      }
    ],
    "program_name": "Rewards",
    "limit": 25,
    "offset": 0
  },
  "meta": {
    "request_id": "req_loyalty_list",
    "timestamp": "2026-09-08T12:04:00Z"
  }
}

Errors worth branching on

These five failures cover the loyalty surface above — read your program (GET /program), balance reads (GET /members, GET /members/:contactId), and burns (POST /members/:contactId/redeem). Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_loyaltya1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_loyaltya1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope (contacts:read for balance/program/preview reads, contacts:write to burn or adjust) — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema, or a burn invariant

The schema rejection:

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "points", "value": "-5", "expected": "a non-negative integer" }
    },
    "meta": {
      "request_id": "req_loyaltyb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A burn that would take the member’s earned balance negative:

  {
    "error": {
      "code": "INSUFFICIENT_POINTS",
      "message": "Insufficient points: available 150, requested 200.",
      "status": 409
    },
    "meta": {
      "request_id": "req_loyaltyb3",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

The 422 case failed schema validation — branch on error.details.field and resend with a non-negative integer for points instead of blind-retrying the same body. The 409 failed the earned-vs-burn invariant — re-read the balance from the ledger (step 3 or 6) and resend with points no greater than available; the API validates the whole request under a per-contact lock, so a burn beyond the balance never writes a reversal that goes negative.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_loyaltyc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

402 — Feature gate

  {
    "error": {
      "code": "LOYALTY_TIER_LIMIT",
      "message": "This loyalty tier is at its enrolled-member cap for the current plan.",
      "status": 402,
      "details": { "tier": "gold", "enrolled": 10000, "limit": 10000 }
    },
    "meta": {
      "request_id": "req_loyaltyd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface plan upsell — no retry path opens until the limit is raised.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
409 `INSUFFICIENT_POINTS`	the burn exceeds the earned balance	Re-read, then resend. Fetch the member balance (step 3) and send `points` no greater than `available`; never a negative-balance debit.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`LOYALTY_TIER_LIMIT` (402 feature gate)	Surface plan upsell	Branch on `error.code`. No retry path opens until the limit is raised.

API Reference

All Endpoints

Worked request and response samples

1. Read the active loyalty program

2. Enroll a member — send their first behavioural event

3. Accrue points

4. Preview a redemption (simulate)

5. Burn — redeem from a member’s balance

6. Page the member ledger

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema, or a burn invariant

429 — Rate

402 — Feature gate

60-second retry matrix

​Worked request and response samples

​1. Read the active loyalty program

​2. Enroll a member — send their first behavioural event

​3. Accrue points

​4. Preview a redemption (simulate)

​5. Burn — redeem from a member’s balance

​6. Page the member ledger

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema, or a burn invariant

​429 — Rate

​402 — Feature gate

​60-second retry matrix

Worked request and response samples

1. Read the active loyalty program

2. Enroll a member — send their first behavioural event

3. Accrue points

4. Preview a redemption (simulate)

5. Burn — redeem from a member’s balance

6. Page the member ledger

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema, or a burn invariant

429 — Rate

402 — Feature gate

60-second retry matrix