Manually adjust a loyalty member's points balance (admin)

A birthday bonus, a correction, a chargeback clawback: the ONE trigger the loyalty wallet-card push engine has today (migration 0161). There is no automatic points-accrual formula for completed bookings anywhere in this product yet, so nothing else calls this.

delta is a signed, non-zero integer added to points_balance via book_loyalty_adjust_points, a security definer RPC rather than a plain PostgREST update: PostgREST cannot express points_balance = points_balance + delta atomically, and a read-then-write from this route would race under concurrent adjustments. The RPC leans on book_loyalty_members.points_balance >= 0 (migration 0160) as the single source of truth for the floor, so a delta that would take the balance negative is rejected by the database, not by application logic re-implementing the same rule.

Every adjustment is recorded in book_loyalty_point_adjustments (company, member, delta, an optional reason, and who made it) for a durable audit trail: redeemable points are worth being able to explain.

No Idempotency-Key, unlike /api/payments/refunds. That machinery exists there because a retry calls an external payment processor that could double-charge with no way to detect the duplicate. A double-submitted delta has no such blast radius: it is one UPDATE against this database, its result is returned in this same response, and it is trivially correctable with the opposite delta.

On success, enqueues loyalty_pass_push so both wallets pick up the new balance: Apple via a silent APNs wake-up that makes the device re-fetch its pass, Google by re-patching the LoyaltyObject directly. That enqueue is best-effort and never fails this request: a queue hiccup must not turn a successful points adjustment into a client-visible error.

Not engine-gated: a loyalty member hangs off book_customers, a table both engines already share, and carries no engine column at all.

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

curl -X PATCH "https://example.com/api/loyalty/members/497f6eca-6276-4993-bfeb-53cbbbba6f08/adjust" \  -H "Content-Type: application/json" \  -d '{    "delta": 0  }'

{  "ok": true,  "member": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "pointsBalance": 0,    "tier": "string",    "status": "string"  },  "delta": 0,  "reason": "string"}