Loyalty Program Architecture

Loyalty Program Architecture

This skill activates when an architect is designing or reviewing a Salesforce Loyalty Management program before the implementation team starts configuring it. It produces the architectural decisions that shape every downstream choice in integration/loyalty-management-setup: how many tiers, what their thresholds are, how qualifying and non-qualifying currencies split, fraud-prevention controls, partner network topology, and tier-descalation rules. The setup skill answers "how do I configure this." This skill answers "what should we configure, and why?"

Before Starting

Gather this context before working on anything in this domain:

• A loyalty program is a point-economy decision before it is a Salesforce configuration. Tier thresholds, accrual rates, and redemption ratios are hypotheses about customer behavior. Get the marketing/finance owner to commit to specific business targets (lifetime value uplift, retention rate, tier distribution) before discussing object models.
• Salesforce Loyalty Management's two-currency model (qualifying vs non-qualifying) is non-negotiable: qualifying points drive tier advancement, non-qualifying points drive redemption. Conflating them in design produces an unimplementable program. Confirm the customer understands the split before tier design begins.
• Tier inflation is the leading cause of loyalty-program failure: thresholds are set generously at launch to drive adoption, then half the customer base lands in the top tier within 18 months and the program loses differentiation. Build tier-descalation into the architecture, not as an afterthought.
• Partner loyalty is a separate architectural problem from B2C loyalty. The LoyaltyProgramPartner model accommodates partner-earned and partner-redeemed transactions but architectural decisions (accrual factor, redemption factor, ledger transparency, fraud isolation) must be made before configuration.
• The DPE (Data Processing Engine) is the heartbeat of the program. Architecture must be DPE-aware: the cadence of "Reset Qualifying Points," "Aggregate Non-Qualifying Points," and "Update Partner Balance" jobs determines what's in scope for tier-realtime vs tier-batch decisions.

Core Concepts

Tier Ladder Design: Threshold Mathematics

Tier thresholds are not arbitrary. They are derived from the customer transaction-volume distribution and a target tier-distribution policy. A typical good architecture targets a 10/30/60 or 5/20/75 Gold/Silver/Bronze distribution — most members in the lowest tier, a meaningful but not majority middle tier, an aspirational top tier.

To derive thresholds:

1. Pull the per-customer annual qualifying-equivalent (e.g., dollars spent or trips taken) over the last 12 months.
2. Compute the percentile distribution. The Gold threshold sits at the customer-count percentile that maps to your target Gold population (e.g., the 90th percentile if Gold should be 10%).
3. Stress-test: if every customer doubles their behavior in year 2, what does the tier distribution become? If you'd land at 30% Gold, the threshold is too low.

Three-tier programs are the canonical baseline (Bronze / Silver / Gold). Five-tier programs (adding Platinum and Diamond, or Member / Bronze / Silver / Gold / VIP) are justified when the customer base has long-tail "VIP" behavior (top 1% spend 10× the median) and you need a separate aspirational tier.

Qualifying vs Non-Qualifying: The Exchange-Rate Question

Members earn both qualifying points (tier currency) and non-qualifying points (redemption currency) on the same transaction. The architecture decision is the ratio.

A common model: 1 qualifying point per $1 spent (tier driver), and 10 non-qualifying points per $1 spent (redemption driver). The 1:10 ratio gives reward statements visual heft ("you earned 1,000 points!") without inflating tier qualification.

Architectural pitfall: setting the qualifying-to-non-qualifying ratio identical (1:1) makes the marketing team mentally collapse them, then start writing redemption rules against qualifying balance — which breaks the tier engine because qualifying balance is reset annually. Force the ratio to be visibly different (1:5, 1:10, 1:100) to keep the two currencies psychologically distinct.

Fraud Prevention: Pre-Aggregation Vs Post-Detection

Loyalty programs attract fraud at three layers:

1. Accrual abuse — gaming the earn rules (returned items still earned points; points awarded twice for the same transaction).
2. Redemption abuse — using points fraudulently obtained or pooled across accounts.
3. Tier-laddering abuse — engineered transactions to hit a tier threshold then unwound (e.g., book a trip for tier credit, then cancel without losing the tier).

Architecture controls that must be in the design:

• DPE-driven pre-aggregation with anomaly thresholds: the accrual DPE flags transactions above a per-account daily/weekly cap for manual review.
• Redemption holds: large redemptions (above an architecture-defined threshold) go to a queue, not auto-process.
• Tier-credit reversals: tier-credit posting DPE accepts return/cancellation events and reverses the qualifying-points award. Without this in the architecture, members earn tier on phantom transactions.

Partner Loyalty: Hub-And-Spoke Vs Peer-To-Peer

Partner loyalty extends the program to ecosystem partners (hotel + airline + car rental; bank + retailer; pharmacy + insurance). The architectural choice:

• Hub-and-spoke — your program is the hub; partners are spokes. Each partner has its own LoyaltyProgramPartner record with accrual and redemption factors. Members earn at any partner; redemption happens against your central currency. The hub owns the ledger.
• Peer-to-peer — multiple programs federate. Each program owns its members; reciprocal earning happens via cross-program APIs. Complex, used by airline alliances. Salesforce Loyalty Management primarily supports hub-and-spoke; peer-to-peer is custom.

Architectural decisions for hub-and-spoke: accrual factor per partner (1.0 = parity, 1.5 = bonus partner), redemption factor (how many central points equal a partner-side reward), partner ledger visibility (does the partner see member balances or only their own transaction posts).

Multi-Region Federation

A single program across US/EU/APAC has architectural choices:

The decision driver is usually regulatory (GDPR data residency forces federation in EU) or transactional (if 30% of members earn in multiple regions, federation is operational pain).

Tier Descalation Policy

Most programs spend 2 years promoting members up the ladder, then realize they have no rule for keeping them at the top tier (or dropping them gracefully). Architecture must answer four questions:

Without an architectural answer, each of these gets implemented ad-hoc and produces a mess.

Common Patterns

Pattern 1: Three-Tier Consumer Program With Annual Reset

When to use: First-time loyalty program for a B2C brand, transactional volume of 100k–10M members.

How it works:

1. Tier ladder: Bronze (entry, automatic on enrollment) / Silver (90th percentile spend) / Gold (99th percentile spend). Target distribution 75/20/5.
2. Currency design: 1 qualifying point per $1, 10 non-qualifying points per $1. Visible ratio prevents mental collapse.
3. Annual qualifying reset on member's anniversary date (avoids January DPE-overload).
4. Soft-landing tier descalation: a member who misses the threshold drops one tier at the next anniversary and earns at the lower rate; they don't drop two tiers in a single reset.
5. Fraud controls: DPE flags >$5,000/day per-account accrual, redemptions over 50k points go to manual review.

Why not the alternative: Five-tier programs at 100k members produce tier populations < 1% in the top tier — too small to drive aspirational behavior. Stick with three until you have the long-tail data to justify more.

Pattern 2: Hub-And-Spoke Partner Loyalty (Travel Alliance)

When to use: Brand owns the central program (e.g., a hotel chain) and partners with airlines, car rental, dining for cross-earning.

How it works:

1. Central program owns the master LoyaltyProgram and member ledger.
2. Each partner is a LoyaltyProgramPartner with explicit accrual factor (e.g., 0.5 for non-strategic partners, 1.0 for parity, 1.5 for promo partners).
3. Partner-earned transactions post to the central ledger via Partner DPE jobs (Create Partner Ledgers, Update Partner Balance — both must be activated).
4. Redemption happens centrally; partner-side rewards come out of the central non-qualifying balance with a configured redemption factor.
5. Fraud controls per partner: rate limits per partner-day to catch a compromised partner-feed.

Why not the alternative: Peer-to-peer partner loyalty (each partner runs their own program; programs federate) is feasible but custom. Salesforce Loyalty Management is built for hub-and-spoke; fight that pattern only when you must.

Pattern 3: Multi-Region Federated Programs With Cross-Earn API

When to use: US + EU + APAC coverage with GDPR data residency forcing region-local programs.

How it works:

1. Three LoyaltyProgram records, one per region. Each owns its members and ledger.
2. Cross-region earn handled via a custom federation API: when a US member transacts in EU, the EU program emits a Platform Event; the US program subscribes and posts qualifying + non-qualifying points to the US member.
3. Tier mapping table: US Gold = EU Premier = APAC Platinum (configured at enrollment by region).
4. Lifetime tier achievements roll up to a per-member "global tier" custom field, calculated by a quarterly DPE reconciliation.
5. Marketing communications respect regional preferences (don't email US-tier upgrades to an EU member).

Why not the alternative: A single global program runs into GDPR data-residency issues (member data must reside in EU for EU members). Federation is the cost of compliance.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an architect or AI agent working on this task:

1. Confirm business targets. Get marketing/finance to commit to lifetime-value uplift, retention rate, and target tier distribution. Without these, tier thresholds are guesses.
2. Model the member base. Pull customer transaction-volume data for the last 12 months. Compute percentile distribution of qualifying-equivalent transactions per member.
3. Design the tier structure.
   • Propose tier thresholds derived from the distribution and target distribution. Stress-test under "all members double behavior" and "all members halve behavior" scenarios.
   • Design tier descalation: reset cadence, grace period, lookback window, lifetime-status policy. Document the member-experience text that explains the rule.
4. Design the currency and accrual controls.
   • Currency split: pick a visibly distinct ratio between qualifying and non-qualifying (1:5 to 1:100). Document the redemption-to-qualifying logic so the marketing team can build redemption rules without bleeding into tier logic.
   • Fraud controls: per-account daily/weekly accrual caps, redemption holds, tier-credit reversal pipeline. Document the DPE jobs that enforce each.
5. Decide the topology extensions (if applicable).
   • Partner topology: hub-and-spoke is the default. Document accrual factor per partner and the partner-DPE schedule.
   • Multi-region pattern: federation is the GDPR-safe default.
6. Hand off to integration/loyalty-management-setup for configuration. Provide the architecture document as the input; the setup skill consumes it.

Review Checklist

Run through these before marking architectural work in this area complete:

• Business targets are explicit (lifetime value uplift, retention rate, tier distribution)
• Tier thresholds are derived from the customer-distribution percentile, not from competitor benchmarking alone
• Currency ratio (qualifying:non-qualifying) is visibly distinct (1:5 to 1:100)
• Fraud-prevention controls are designed (accrual caps, redemption holds, tier-credit reversal)
• Partner topology decision is documented (if applicable): hub-and-spoke vs peer-to-peer, accrual factors per partner
• Multi-region federation decision is documented (if applicable) with regulatory rationale
• Tier-descalation policy is explicit: reset cadence, grace period, lookback, lifetime-status rules
• DPE schedule is documented: which jobs run at what cadence, what their dependencies are
• Stress-test scenarios documented: how does the tier distribution evolve under behavior shifts
• Architecture document handed off to the setup team with a clean spec

Salesforce-Specific Gotchas

(Detailed entries live in references/gotchas.md.)

1. Point inflation is the most common program failure — without a descalation rule, members concentrate in the top tier within 18 months.
2. Identical qualifying:non-qualifying ratio invites mental collapse — marketing teams will write redemption rules against qualifying balance and break tier logic.
3. DPE schedule constraints on architecture — qualifying-reset DPE runs on a schedule, not real-time; "instant tier upgrade on hitting the threshold" is not a supported pattern.
4. Partner DPE jobs are not on by default — architecture must specify which jobs are activated and on what cadence.
5. Tier-credit reversals aren't automatic — return/cancel events must be wired into the architecture or members earn tier on phantom transactions.

Output Artifacts

Related Skills

• integration/loyalty-management-setup — the implementation skill that consumes this architecture
• admin/rebate-management-setup — for B2B channel partner incentive programs (often confused with B2B partner loyalty)
• architect/multi-org-strategy — for the multi-region federation decision-making
• integration/data-cloud-integration-strategy — if loyalty data feeds Data Cloud for customer 360 / segmentation
• architect/event-driven-architecture — for the cross-region federation Platform Event pattern in multi-region designs