SfSkills Domains Docs GitHub

Home / architect / loyalty-program-architecture

loyalty-program-architecture

Use when designing or reviewing the architecture of a Salesforce Loyalty Management program before configuration begins — tier-ladder economics, qualifying-vs-non-qualifying currency split, point inflation/deflation modeling, fraud-prevention controls, partner-network topology, multi-region program federation, and tier-descalation policy.

Open the skill folder on GitHub

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:

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:

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:

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:

PatternWhen to useTradeoff
Single program, multi-regionBrand parity is paramount; transactions are cross-regionCurrency conversion, tax / GDPR complexity, single DPE schedule
Federated programs (one per region)Local regulatory requirements (GDPR data residency, EU prize regulations)Members can't earn cross-region without a federation API
Tiered hybridPremium tier is global, base tier is regionalMost complex; needs explicit tier-mapping rules

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:

QuestionCommon answersNotes
Reset cadenceAnnual, biennial, neverAnnual is most common; aligns with most marketing cycles
Grace periodSame-day drop, or 3–12 month soft landing at current tier with lower earn rateSoft landing is the better member experience but adds DPE complexity
Lookback windowCalendar year, or rolling 12 monthsRolling smooths the member experience but the tier process must re-assess monthly
Lifetime statusYes (e.g., 1M miles → Platinum forever) or noLifetime ledger never expires; plan a rolled-up summary on the member object

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 through one DPE definition, cloned from the Create Partner Ledgers and Update Partner Balances template, activated, and run from a flow after partner transactions are processed. Set BillingType and the cost-per-unit fields on each LoyaltyProgramPartner first. Source: Loyalty Management guide (Spring '26), Create Partner Ledgers and Update Partner Balances Definition; see integration/loyalty-management-setup Gotcha 4.
  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

SituationRecommended ApproachReason
First-time consumer loyalty program, B2C, 100k–10M members3-tier program with annual reset, 1:10 currency ratioCanonical baseline; complexity scales later if data justifies
High-end brand with long-tail VIP behavior (top 1% spend 10× median)5-tier program with separate aspirational top tierDifferentiation requires a Platinum/Diamond layer
Partner ecosystem (airlines + hotels + dining)Hub-and-spoke with central programSalesforce Loyalty Management is built for this pattern
US + EU + APACFederated programs (one per region)GDPR data residency forces regional separation
B2B distribution channel rewardsLoyalty Management with Partner LoyaltyChannel programs work but consider Channel Revenue Management for incentives proper
Loyalty + Marketing Cloud existingLoyalty Management is the system of record; MC is the engagement channelDon't try to use MC engagement programs to replace loyalty tier engine
Subscription-based product (e.g., SaaS)Treat tier as account-state, not point-stateLoyalty Management is built for transaction-driven programs; subscription state belongs in custom logic
Concerns about point-redemption fraudBuild pre-aggregation DPE controls + redemption holds + tier-credit reversal pipelineFraud is a design issue, not a runtime issue

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:

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. Tier upgrades follow the Change Tier process, not a DPE job — the generated process runs in real time (as a child of a Transaction Journal process) or in batches through Batch Management; the qualifying-reset DPE definition runs only when a flow calls it. Architecture must choose real-time vs batch and state the resulting upgrade SLA. Source: Loyalty Management guide (Spring '26), Tier Assessment; see integration/loyalty-management-setup Gotcha 2.
  4. DPE templates do nothing until cloned, activated, and run from a flow — architecture must specify which definitions are cloned and what flow cadence runs them. Partner ledgers and balances need only one definition.
  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

ArtifactDescription
Architecture DocumentTier ladder, currency design, fraud controls, partner topology, multi-region pattern, tier-descalation policy
Tier Threshold DerivationPercentile distribution analysis, threshold proposals, stress-test scenarios
DPE Schedule SpecWhich DPE jobs run at what cadence, dependency graph, failure-handling expectations
Fraud Control MatrixPer-control-type: accrual caps, redemption holds, tier-credit reversal, anomaly thresholds, manual review queues
Partner Topology Diagram (if applicable)Hub-and-spoke layout, accrual/redemption factors per partner, partner-ledger visibility
Multi-Region Federation Diagram (if applicable)Per-region program, cross-earn API design, tier mapping table
Setup Hand-Off SpecDocument the setup team uses to drive integration/loyalty-management-setup configuration

Package files