LoyaltyProgram
object type
A LoyaltyProgram — the points engine's GROUP-scoped rule master: members EARN points on net merchandise spend (floor(base × earnRate.points ÷ earnRate.perMinor) — floor ONCE at the order level over the FINAL post-redemption discounted taxable bases, storedValue lines excluded) and REDEEM them as a PRE-TAX DISCOUNT at the step-2 position 4 (source=loyalty LINE entries — after manual → coupon → promotion; the taxonomy law: loyalty is a DISCOUNT, categorically NOT a tender — no loyalty tender type exists). currency is EXPLICIT + IMMUTABLE at birth (a group's orgs may differ in defaultCurrency — orders in another currency refuse the attach; FX = the deferral). Earn multipliers COMPOUND multiplicatively across three families — tier × active bonus window × MAX(matching predicate rows, never stacked) — each family ≤ 8 rows. Org participation is the canned-pool selection (organizationIds ABSENT = every org in the group). The effective window is half-open [startAt, endAt) — an EVALUATION gate, never FSM states. At most 8 ACTIVE per org group. Doom is -gated by non-doomed members (doom the members first); deactivate stays FREE. Tier ASSIGNMENT is a manual member edit v1 (the auto-evaluation sweeper is a NAMED deferral); points expiry/transfer, redemption caps, ecom/non-sale loyalty and fraud velocity are the NAMED deferrals.
Fields
| Field | Type | Notes |
|---|---|---|
id | ID ID! | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
sysId | String String! | The group-scoped human-facing system id (LP-…). |
type | String String! | The kind of record — always LoyaltyProgram here. |
caption | String String! | The record’s display name — what people see it called. |
status | String String! | The FSM state: active | inactive | doomed. |
parentId | ID ID! | The parent org group; for a LoyaltyProgram parentId === rootId. |
rootId | ID ID! | The org-group family root. |
createdAt | String String! | When the record was created, as a UTC timestamp. |
updatedAt | String String! | When the record last changed, as a UTC timestamp. |
revisionNum | Int Int! | How many times this record has been edited; the first save is 0. |
revision | ID ID! | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
refCaptions | RefCaption [RefCaption!]! | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
currency | String String! | The program earn/redeem currency (ISO-4217) — EXPLICIT + IMMUTABLE at birth. |
earnRate | LoyaltyRate LoyaltyRate! | Earn points per perMinor of eligible spend. |
redeemRate | LoyaltyRate LoyaltyRate! | points convert to perMinor of pre-tax discount value. |
earnMultipliers | LoyaltyEarnMultiplier [LoyaltyEarnMultiplier!] | Category/product earn multipliers — matching lines take the MAX row (never stacked); compounds with tier × bonus. |
bonusWindows | LoyaltyBonusWindow [LoyaltyBonusWindow!] | Time-boxed bonus-earn windows (≤ 8; BOTH bounds required, half-open) — overlapping windows take the MAX; a PROGRAM rule, deliberately NOT a promotion effect. |
tiers | LoyaltyTier [LoyaltyTier!] | Named tiers (≤ 8; unique names) — config + benefit math ship v1; ASSIGNMENT is a manual member edit and auto-evaluation is the deferral. |
organizationIds | ID [ID!] | The canned-pool org selection — ABSENT = every org in the group participates. |
startAt | String String! | The half-open window start (UTC ISO-8601; kit-stamped NOW when omitted at create) — IMMUTABLE at birth (the history anchor). |
endAt | String | The half-open window end — ABSENT = evergreen; [startAt, endAt) is an EVALUATION gate. |