Designing a Multi-Balance Loyalty Subledger Model

Hello. This module develops the loyalty-program design decisions that sit behind later rule configuration and integration work. A loyalty program can hold more than one usable points balance for the same member; the architectural question is when those balances should be separate, what each represents, and how every earn, redemption, and rollback remains attributable to the right balance.

In this lesson, you will define a subledger model: a durable model for partitioning points within one Talon.One loyalty program. The emphasis is not merely on creating a subledger in the Rule Builder, but on making a defensible decision about its business meaning, identifiers, rule boundaries, integration context, and operational consequences.

---

Subledgers: separate wallets, shared loyalty program

A Talon.One subledger is an individual loyalty-points wallet inside a single loyalty program. One member can therefore have several independent balances while remaining in the same program.

Consider a retail group with one customer-facing program, Northstar Rewards. A member might hold these balances:

Loyalty program	Subledger	Available points	Meaning
Northstar Rewards	main	900	Points usable across the group
Northstar Rewards	store-berlin-017	160	Points earned and redeemable at the Berlin store
Northstar Rewards	partner-airline	2,500	Partner-funded points with partner-specific redemption rules

This is not three memberships. It is one loyalty relationship with three separately governed point wallets.

The critical principle is:

A subledger represents a businessly meaningful partition of point fungibility.

“Fungibility” here means whether points can be substituted for one another. If 100 points earned in Store A may not be spent in Store B, they are not fungible and belong in different subledgers. If points are usable everywhere but a campaign should only target customers in Germany, the points remain fungible; use targeting or attributes rather than creating a German subledger.

What a subledger is not

Avoid using a subledger as a generic categorization device.

Requirement	Usually the right mechanism	Why a subledger is usually wrong
Restrict a promotion to VIP customers	Profile attribute or audience	The restriction is about eligibility, not where points may be spent.
Track pending versus available points	Loyalty point state	Talon.One already distinguishes these balance states.
Identify the campaign that awarded points	Point transaction metadata and rule/effect information	A wallet per campaign rapidly becomes unmanageable.
Separate legal entities, tenants, or customer datasets	Application and/or loyalty-program boundary	A subledger partitions balances, not the full security and data-isolation model.
Store-specific point earning and redemption	Subledger	The points have a clear restricted-use boundary.

A useful architecture test is: Would a customer reasonably expect these balances to appear as distinct balances in their wallet or loyalty statement? If not, a subledger may be imposing technical structure where business policy does not require it.

---

The three balance views within a subledger

Each subledger has balance states. These states are views of one wallet, not additional subledgers.

The states are:

• Current Balance: points available immediately after a purchase has been recorded.
• Pending Balance: points awarded for a purchase but unavailable until a defined period has passed.
• Tentative Current Balance: the in-session view that includes additions and deductions being evaluated during an active customer session.

Suppose the store-berlin-017 wallet begins with:

• Current Balance: 160
• Pending Balance: 40

During a new checkout, qualifying items earn 30 points and the customer redeems 100 points. The tentative balance for that wallet is 90 points:

$$160+30-100=90$$

The pending 40 points remain a separate state: they are not casually treated as immediately spendable just because they are visible in the customer’s overall loyalty record.

This distinction has practical rule-design consequences. A rule permitting a redemption should validate the relevant balance state in the relevant subledger. A rule that validates only a global-looking total can accidentally approve a redemption that violates a store, partner, or funding restriction.

Subledger identity versus Rule Builder accessor

There are two names worth separating in your design:

1. Subledger ID/name
   The durable business identifier, such as store-berlin-017 or partner-airline. Talon.One returns it as subLedgerId in loyalty effects.

2. Subledger accessor
   The readable name used in a campaign’s Rule Builder attribute selector, such as “Berlin available points.”

Treat the accessor as authoring configuration. Treat the subledger ID as an integration and governance contract.

For example, a rule author may use the accessor Berlin Store Balance, but downstream reconciliation should identify the wallet with subLedgerId: "store-berlin-017", not with a UI-oriented label. This lets labels evolve without forcing every commerce, reporting, and finance integration to change.

---

Designing the subledger model

A durable model starts from the business invariant that must always remain true. For the Berlin store example:

Points funded by Berlin Store 017 can be redeemed only in Store 017, and every award, deduction, expiry action, and rollback remains attributable to that store.

That invariant gives the subledger its purpose. Design from this level rather than starting with the number of stores or campaigns.

A six-part design method

1. State the partitioning rule in one sentence.
   Specify what makes one point balance different from another. Good examples include “points are redeemable only at the issuing franchise” or “partner-issued points fund only partner rewards.”

2. Choose the scope that owns the balance.
   Common scopes are a physical store, franchise, brand, partner, business unit, or funded reward pool. Choose a scope with an authoritative enterprise identifier.

3. Define a stable machine identifier.
   A store subledger should derive from the store-master identifier, not from a marketing label. For instance, store-berlin-017 is safer than Berlin Flagship; the latter may change after a relocation or rebrand.

4. Define earning and redemption boundaries separately.
   “Earn at X” does not automatically imply “spend only at X.” Make each rule explicit. A model may permit points earned at any local store to be redeemed only locally, or it may permit local earning but central redemption from main.

5. Specify the context the commerce integration must supply.
   Rules need a reliable way to know which business scope applies. For a store model, every relevant customer session should carry an authoritative store identifier such as fulfillmentStoreId or transactionStoreId. Do not rely on an editable display name or loosely inferred location.

6. Define lifecycle and reconciliation behavior.
   Award, redemption, cancellation, partial return, expiry, and support adjustments must all preserve subledger attribution. The rule engine’s effects provide that attribution through programId and subLedgerId.

A practical design record

For architect review, write the model down as a small contract rather than leaving it implicit in rule names.

Field	Example decision
Program	Northstar Rewards
Subledger ID	store-berlin-017
Business owner	Berlin Store 017 franchise
Authoritative source for ID	Enterprise store master
Earning scope	Purchases whose transactionStoreId is BER-017
Redemption scope	Checkout at BER-017 only
Balance checked for redemption	Current Balance, then Tentative Current Balance during session evaluation where appropriate
Customer wallet label	Berlin Store points
Rule accessor	Berlin Store Balance
Reporting key	Program ID plus subledger ID
Closure/rollback policy	Point changes become persistent on closed session; reversal effects must be reconciled to the same subledger

This record prevents an especially common failure: a campaign rule is configured for a local wallet, but the checkout service displays or redeems the customer’s aggregate points without respecting the local restriction.

When one program with subledgers is the wrong boundary

Subledgers are valuable because they avoid duplicating a program merely to isolate balances. But they do not erase every reason to use separate program or Application boundaries.

Escalate the design decision when the proposed partitions have materially different:

• legal ownership or accounting obligations;
• member enrollment terms;
• currencies or point economics that cannot be coherently explained as one program;
• data-isolation or access-control requirements;
• operational teams that must deploy and govern independently.

The question is not “Can we create a subledger?” It is “Does a shared loyalty program still represent one coherent customer promise?”

---

Rules and the runtime integration contract

In Talon.One, a campaign must have loyalty enabled, and the loyalty program must support subledgers. Rule authors then create or select an accessor in the Rule Builder, use that accessor in balance conditions, and configure effects that add or redeem points in that subledger.

The integration does not need to infer the wallet from effect order. Loyalty effects identify the program and subledger explicitly.

A representative addition effect has this shape:

{
  "effectType": "addLoyaltyPoints",
  "props": {
    "name": "Points for Berlin purchase",
    "programId": 5,
    "subLedgerId": "store-berlin-017",
    "value": 30,
    "recipientIntegrationId": "customer-4821",
    "transactionUUID": "transaction-uuid"
  }
}

At runtime, your adapter should treat the combination below as the business routing identity:

$$(\text{programId},\text{subLedgerId},\text{transactionUUID})$$

The profile or card identifier identifies whose balance moved. The program and subledger identify which balance moved. The transaction identifier supports reconciliation of the specific movement.

Persistence and reversals

The Talon.One effect documentation notes that additions and deductions persist when the customer session closes. That means an open checkout can produce a provisional decision view, while closure makes the loyalty movement durable.

Your design should therefore state these operational rules:

• Only present a balance as final after the corresponding transaction state is final in the intended commerce workflow.
• Keep the returned loyalty transactionUUID, program ID, and subledger ID in reconciliation records.
• Process rollback effects as compensating movements, not as new unrelated activity.
• Never assume that a cancellation or partial return concerns the main balance; inspect subLedgerId on the effect.

This is also why a vague design such as “all store points” is insufficient. An effect processor needs an exact wallet identity, and finance or support teams need to explain the resulting transaction history.

---

Sandbox implementation: one restricted-store wallet

Use your sandbox to turn the model into a small, inspectable configuration. Keep the scope deliberately narrow: one store and one customer journey.

1. Select or create a loyalty program that supports subledgers, then ensure loyalty is enabled in the campaign you will use.
2. Define the business record:
   • Subledger ID: store-berlin-017
   • Meaning: points funded by and spendable at Berlin Store 017
   • Required session context: transactionStoreId = "BER-017"
3. In the campaign’s Rule Builder, use Access subledgers to create the store-berlin-017 subledger and save a readable accessor such as Berlin Store Balance.
4. Create an earning rule whose conditions identify Berlin-store transactions and whose loyalty effect adds points to the Berlin wallet.
5. Create a redemption rule that checks the Berlin accessor’s balance and deducts from the same subledger.
6. Run an eligible session through the Integration API and inspect returned effects. Confirm that both the earning and redemption effects contain the intended subLedgerId.
7. Close the test session only when you intend the point movements to persist. If your sandbox workflow permits, test a cancellation afterward and confirm the rollback remains attributed to store-berlin-017.

As you do this, record what source supplies transactionStoreId. If the answer is “the front end sends it,” that is not yet a sufficient architecture decision. Decide whether the commerce backend can validate it against the order, fulfillment, or store-master context before Talon.One evaluates the transaction.

---

Design guardrails

A few guardrails keep subledger designs maintainable at enterprise scale:

• Keep the number of wallets intelligible. A member should not acquire a wallet per campaign, SKU, or order unless that fragmentation is genuinely part of the loyalty proposition.
• Use IDs from master data. If stores, partners, or franchises own the balance scope, synchronize and govern their identifiers as enterprise reference data.
• Make redemption policy visible. A customer-facing wallet display, checkout experience, and service-agent tooling must not imply that a balance is spendable where the rules forbid it.
• Keep one source of truth for point movements. Talon.One loyalty effects describe the point movements the integration must reconcile; do not maintain an independently calculated duplicate balance that can drift.
• Test negative cases. A customer with 500 points in main and 0 points in store-berlin-017 is the essential test case for a Berlin-only redemption rule.
• Plan for retirement. If a store closes, define whether its points migrate, remain redeemable elsewhere, expire under policy, or require a service process. The answer is a business decision that must be reflected in rules and customer communication.

---

A subledger is a named points wallet within one loyalty program, best used when points differ in where they may be earned, spent, or financially attributed. The model needs a stable subledger ID, a clear ownership scope, explicit earn and redemption boundaries, reliable transaction context, and effect-based reconciliation keyed by programId and subLedgerId.

Next, the course will build on this foundation by examining point activation and expiration behavior: when earned points become usable, how long they remain valid, and how those policies interact with the balances you have now partitioned.