Promotion Lifecycle: Qualification, Reward Calculation, Redemption, and Fulfillment

Welcome. This first module establishes the promotion vocabulary that underpins every later Talon.One design decision: how a business offer becomes a decision, a reward, and ultimately a customer-visible outcome.

A promotion is often described in customer language as “enter a code and get 10% off.” That description collapses several distinct responsibilities. For solution architecture, separating them matters: it determines what Talon.One decides, what the commerce platform must do, when scarce benefits are committed, and what must be reversed if an order fails.

By the end of this lesson, you should be able to classify each action in a promotion journey as qualification, reward calculation, redemption, or fulfillment—and recognize where those phases overlap without treating them as interchangeable.

---

One business promise, four lifecycle stages

Consider this offer:

“Customers who enter a valid XMAS coupon and spend at least USD 100 receive 10% off. The coupon may be used once.”

The promotion lifecycle can be expressed through four questions:

Stage	Core question	Typical output
Qualification	Does this customer action meet the offer’s conditions?	Eligible or ineligible, often with a reason
Reward calculation	If eligible, what benefit is due?	A specific discount, points amount, free item, or other effect
Redemption	Has the customer actually consumed a limited offer or value?	Coupon usage, referral usage, or point deduction committed
Fulfillment	Has the promised benefit been delivered in the operational system?	Adjusted price, added item, shipment, message, or entitlement

These are responsibility boundaries, not always four consecutive timestamps. For example, a storefront may fulfill a discount in its cart calculation before the order is finalized, while Talon.One commits coupon redemption when the customer session closes. A customer can therefore see a discount before the coupon’s use is final.

This distinction prevents two costly errors:

1. Treating a provisional promotion response as a completed transaction. A cart can change, payment can fail, and an order can be cancelled.
2. Assuming Talon.One has altered an external commerce system merely because it returned a discount effect. For most external outcomes, Talon.One makes the decision; the integration delivers the result.

Before examining each stage, read Talon.One’s description of how it evaluates campaigns and produces effects.

---

Qualification: deciding whether the offer applies

Qualification is the Rule Engine’s determination that the requirements for an offer have been met. It answers whether the customer is entitled to be considered for the reward, not yet how the storefront changes the order.

For the XMAS coupon example, qualification may include all of the following:

• The campaign is active and is eligible for evaluation.
• The submitted code exists, is within its validity period, and has not exceeded its redemption limit.
• The code is valid for this customer, if it is recipient-restricted.
• The cart total meets the USD 100 threshold.
• The customer meets any targeting requirements, such as membership status or market.
• The campaign and its effects still have budget or limit capacity.

Talon.One first evaluates the applicable campaigns, then their rules. Within a rule, it evaluates conditions before applying effects. If a condition is false, the rule fails and the engine continues evaluation according to the campaign configuration.

Qualification is not merely code validation

A coupon can be syntactically correct and known to Talon.One, but still fail qualification because it is expired, tied to another customer, excluded by campaign evaluation, or blocked by a budget or usage constraint. Conversely, the customer’s cart might be eligible for an automatic promotion without entering any code at all.

A useful architectural distinction is:

• Input validity: Can the request be interpreted? For example, is the payload structurally valid?
• Offer qualification: Do commercial rules permit this benefit?
• Transaction success: Was the resulting order ultimately placed and paid for?

These are separate outcomes and should not be collapsed into one generic success state in an integration.

Failure feedback belongs near qualification

Qualification can produce customer-facing feedback even when no reward is calculated. A failure effect such as a notification can explain that a coupon is invalid or that a cart threshold has not been reached. This is useful for experience design, but it is not a financial or loyalty transaction.

For a storefront adapter, a clean model is:

• Qualified: display the offer as applicable and process the computed effects.
• Not qualified: show the applicable explanation, if returned, but do not create a discount or entitlement.
• Indeterminate: the promotion decision could not be obtained; apply the agreed operational fallback rather than pretending the offer was rejected.

---

Reward calculation: deciding the exact benefit

Once a rule qualifies, Talon.One evaluates its effects. Reward calculation determines the concrete benefit for the current session state.

With a cart total of USD 200 and a 10% discount, the calculated reward is USD 20. If the cart later changes to USD 160, the correct reward can become USD 16. The offer has not changed; its calculation has been re-evaluated against a new cart.

In Talon.One, this decision is communicated as one or more effects. Effects are the contract between the Rule Engine and your integration layer.

A discount effect might conceptually look like this:

{
  "effectType": "setDiscount",
  "props": {
    "name": "10% off with XMAS coupon",
    "value": 20.0
  }
}

The engine has determined the discount’s label and amount. It has not, by returning this JSON alone, changed the price in your storefront, tax engine, payment authorization, order-management system, or accounting ledger.

Calculation can be provisional and repeatable

A customer session may be updated many times: an item is added, quantity changes, a coupon is removed, shipping is selected, or the customer signs in. Each update can cause Talon.One to return the current set of applicable effects.

For effect-based integrations, the safe mental model is not “apply the next event in the array.” It is:

Reconcile the current Talon.One decision with the current commerce state.

This is especially important for setDiscount: a more recent session response supplies the latest value for effects of that name. If the adapter repeatedly accumulates discounts from every response, it can double-discount an order.

Reward calculation can also account for constraints. A rule can qualify while a related effect cannot be applied because its budget is exhausted. From the business perspective, the customer did not receive the reward; from the implementation perspective, the integration must respect the returned effects rather than independently recomputing what it believes the customer should receive.

---

Redemption: committing the use of scarce value

Redemption means that a customer consumes a constrained promotional resource or stored value. It is the stage at which “this benefit was used” becomes durable enough to affect future eligibility.

The most common examples are:

• a one-time or limited-use coupon;
• a referral code;
• loyalty points spent for a benefit;
• a limited giveaway or reward inventory item.

Redemption is deliberately different from an eligibility check.

Coupon acceptance is not necessarily coupon redemption

When an open customer session includes a valid coupon, Talon.One can return an acceptCoupon effect. This tells the integration that the code is valid in the current evaluated context. The customer can be told that the coupon is accepted, and the associated discount can be displayed.

However, for coupons, Talon.One automatically redeems the code when the customer session is closed. Typing a code into a cart is therefore not the same as consuming it. This protects both the business and the customer:

• The business does not permanently spend a single-use coupon just because it appeared in an abandoned cart.
• The customer does not lose the coupon when checkout fails before an order is confirmed.

The same pattern applies to referral codes: an accepted referral can be recognized during the shopping journey, while its redemption is committed at the appropriate transaction boundary.

Loyalty has two distinct business actions

Loyalty makes the vocabulary particularly important:

• Awarding points is a reward outcome. The customer earns value.
• Redeeming points is the consumption of existing value to obtain another benefit.

If a campaign gives 100 points for a qualifying purchase, the reward calculation may return addLoyaltyPoints. Those points persist when the session closes. No point redemption occurred.

If a customer spends 500 existing points to receive a USD 5 discount, the calculated effects include a point deduction and a customer benefit. The point deduction is redemption; applying the USD 5 benefit is fulfillment.

Do not use “redemption” as a generic synonym for “customer got a reward.” It means consumption of a redeemable resource.

---

Fulfillment: making the decision real for the customer

Fulfillment is the operational delivery of the reward in the system that controls the relevant outcome. Talon.One produces the decision and, for certain Talon.One-managed entities, records state. The integration layer is responsible for many customer-facing results.

Examples of fulfillment include:

Calculated effect or decision	Typical fulfillment owner	Fulfillment action
Session discount	Commerce or pricing service	Add a named discount to the order total
Item-level discount	Commerce service	Apply the amount to the specified cart item and unit
Free item	Cart or order service	Add the indicated SKU at zero price, subject to product availability policy
Notification	Web or mobile client	Display an offer, information, or error message
Coupon creation	CRM, messaging, or customer-engagement service	Deliver the created code to its recipient
Loyalty points addition	Talon.One, once the session closes	Persist the point transaction in the loyalty program
Giveaway code	Fulfillment or engagement service	Deliver or expose the awarded code only when appropriate

A financial discount is the clearest example of the boundary. A setDiscount effect gives your integration the amount and label; the commerce platform must apply it to its own pricing representation. That commerce platform remains responsible for its downstream concerns, such as tax treatment, payment amount, invoice presentation, and refund policy.

Read the selected portions of the effects reference now. They show this boundary in Talon.One’s own API vocabulary.

---

An end-to-end trace: the XMAS coupon

The following trace separates the four stages without pretending they are always isolated API calls.

1. The shopper supplies a cart and coupon

The commerce service sends an update for an open customer session. The request contains the customer identity where available, cart items and prices, and the coupon code XMAS-2021.

At this point, the code is an input, not proof of a reward and not proof of redemption.

2. Talon.One qualifies the offer

The Rule Engine evaluates the relevant campaign and its conditions. It checks the code, the cart threshold, customer restrictions, campaign status, and applicable limits.

If the code is valid but the cart is below the threshold, the coupon may still be rejected for the requested offer because not all business conditions are met. If all required conditions pass, the rule qualifies.

3. Talon.One calculates the reward

For a qualifying USD 200 cart, Talon.One returns:

• an acceptCoupon effect for XMAS-2021;
• a setDiscount effect such as “10% off with XMAS coupon,” with value 20.0.

The acceptance effect communicates valid coupon status. The discount effect communicates the calculated monetary reward. Neither effect by itself means the payment was successful.

4. The commerce integration fulfills the discount

The storefront or pricing service maps the setDiscount effect to its own discount model. It must show the USD 20 reduction in the cart and ensure that the order total passed to payment reflects the correct price.

The customer can now experience the reward before placing the order. This is fulfillment of the pricing benefit in the cart experience, but the transaction is still pending.

5. The order reaches its committing boundary

When the business regards the order as sufficiently confirmed, it closes the Talon.One customer session. For the accepted coupon, this is the point at which Talon.One automatically redeems it.

The exact choice of close point depends on commerce and payment semantics and will be treated in the transaction-lifecycle module. For now, the essential rule is simple: do not confuse presenting an accepted coupon in an open session with final coupon consumption.

6. An exception may require reversal

If the downstream transaction fails or the order is cancelled, the lifecycle must remain reversible. Talon.One can return rollback effects for previously committed coupon, discount, loyalty, and other outcomes, while the commerce platform reverses its own price, order, or fulfillment actions.

A promotion design is incomplete if it specifies only how a reward is granted. It must also identify what constitutes commitment and how the result is unwound.

---

Architect’s classification guide

When reviewing a requirement, classify each statement before deciding how to configure it.

Requirement statement	Correct classification
“The customer must be in the Gold tier.”	Qualification condition
“The cart must contain two items from category shoes.”	Qualification condition
“Apply 15% off eligible shoes, up to USD 30.”	Reward calculation and constraint
“The code can be used once per customer.”	Redemption constraint
“Deduct 500 points from the customer’s balance.”	Redemption
“Add a zero-priced gift SKU to the order.”	Fulfillment
“Send the customer their newly created coupon.”	Fulfillment
“Display ‘Spend USD 20 more to qualify.’”	Qualification feedback, usually a notification or UI rule
“Persist 100 earned loyalty points after the purchase commits.”	Reward settlement; Talon.One-managed persistence at session close

Two design questions make this classification operational:

1. What data is required to make the decision?
   This belongs to qualification and calculation: customer facts, cart data, coupon state, budgets, and campaign configuration.

2. Which system can actually deliver or reverse the result?
   This belongs to fulfillment and subsequent reconciliation: commerce, payment, order management, fulfillment, CRM, or Talon.One’s loyalty and coupon records.

A good integration contract preserves this separation. It receives Talon.One effects, dispatches them by effectType, and maps each type to an explicitly owned action. It does not infer fulfillment merely from rule success, and it does not treat API-array order as business priority.

---

Key takeaways

A promotion lifecycle is more than a rule matching a cart:

• Qualification determines whether the offer’s conditions are satisfied.
• Reward calculation determines the specific benefit for the current evaluated session and returns it as effects.
• Redemption commits consumption of a limited coupon, referral, or loyalty balance; acceptance during an open session is not always final redemption.
• Fulfillment is the delivery of the benefit in the system that owns the practical outcome, often outside Talon.One.
• Effects form the decision contract between Talon.One and the integration layer. A setDiscount effect is a calculated instruction, not an automatic modification of the commerce order.
• A durable design defines both the commitment boundary and the rollback path.

Next, you will translate a business objective into the four ingredients that make this lifecycle executable: a trigger, eligibility criteria, a reward, and constraints.