Tracing Customer Actions Through the Integration API and Rule Engine

Welcome back. In the previous lesson, you made discounts commercially precise by defining their base, scope, cap, and rounding behavior. That work becomes operational only when a commerce system sends the relevant customer action to Talon.One and correctly interprets the decision it gets back.

This lesson follows one action—entering a coupon while editing a cart—from the storefront through the Integration API and Rule Engine to the effects returned to your integration. The central architectural point is simple: Talon.One decides what qualifies and what should happen; the surrounding integration applies the appropriate result in the commerce experience.

---

Four things that must not be conflated

A production trace is much clearer when each stage has a distinct meaning.

Concept	Meaning	Example
Customer action	A business action in your channel	Shopper adds a jacket and enters WELCOME20
Integration API request	The data your system submits to Talon.One	An update to the customer session containing cart items and coupon code
Rule Engine evaluation	Talon.One evaluates active campaign rules against the submitted context	Coupon is valid; jacket is eligible; campaign conditions match
Effects	Structured decision results returned to your system	Accept coupon; apply an item discount

A customer action is not automatically a Talon.One event in the way an event bus might model it. Your system sends an Integration API request, and Talon.One transforms the request into an event for Rule Engine evaluation. The effects in the response are therefore the outcome of evaluating the current submitted state against the currently active campaign configuration.

The phrase “only coupling” is important. Your checkout service should not contain copies of campaign logic such as:

• “If coupon starts with WELCOME, apply 20%.”
• “If customer belongs to this segment, discount outerwear.”
• “If campaign is active, show free shipping.”

Those are decision rules and belong in Talon.One configuration. The integration’s responsibility is to supply the facts that rules need, receive the resulting effects, and apply them according to a stable effect-handling contract.

---

The request-and-effects decisioning sequence

At checkout or cart-update time, the high-level interaction looks like this:

The commerce-side promotion adapter is a useful architectural boundary. It translates your channel’s cart, customer, and order representation into Talon.One’s Integration API request, then translates Talon.One effects into operations your cart, pricing, coupon, loyalty, and fulfillment services understand.

This reduces coupling in both directions:

• A campaign manager can revise campaign conditions without requiring the storefront to be redeployed.
• Your commerce domain model can evolve without exposing every internal detail directly to campaign rules.
• Different channels, such as web, mobile, point of sale, and customer service, can use one consistent effect-processing approach.

The adapter does not need to reproduce the Rule Engine. It needs to provide a dependable mapping between the two systems.

---

A worked trace: coupon entered on an open cart

Continue with the cart used in the previous lesson:

Cart item	Quantity	Unit price
Trail jacket	1	USD 120.00
Thermal base layer	2	USD 35.00
Water bottle	1	USD 20.00

Assume a shopper enters the coupon WELCOME20. A configured campaign has the following business behavior:

• The coupon must be valid.
• The cart must contain an eligible Trail jacket.
• The reward is 20% off the jacket’s merchandise price.
• The result is an item-level discount of USD 24.00.

1. The channel captures the business action

The storefront records that the shopper entered a code while the cart is still editable. The storefront does not determine whether the code is valid. It passes the action and current cart state to the commerce backend.

The backend should attach a correlation identifier for the entire request path. For example, one checkout interaction might use:

• Customer-session integration ID: web-cart-8f4c21
• Customer profile integration ID, if known: cust-1042
• Correlation ID: checkout-req-b713

The session integration ID identifies the evolving cart or transaction context in Talon.One. The correlation ID is an observability value used to connect storefront logs, adapter logs, API calls, and order calculations.

2. The promotion adapter builds the customer-session update

For this action, the adapter sends an update to the customer session. Conceptually, the request contains the current state that rules need to evaluate:

{
  "customerSession": {
    "state": "open",
    "profileId": "cust-1042",
    "cartItems": [
      {
        "name": "Trail jacket",
        "sku": "TJ-001",
        "quantity": 1,
        "price": 120,
        "category": "Outerwear"
      },
      {
        "name": "Thermal base layer",
        "sku": "TB-002",
        "quantity": 2,
        "price": 35,
        "category": "Base layers"
      },
      {
        "name": "Water bottle",
        "sku": "WB-003",
        "quantity": 1,
        "price": 20,
        "category": "Accessories"
      }
    ],
    "couponCodes": [
      "WELCOME20"
    ]
  }
}

This is deliberately a current-cart representation. The jacket price sent to Talon.One is USD 120.00, not the USD 96.00 discounted price that the shopper may eventually see. The Rule Engine needs original commercial prices to recalculate correctly when the coupon is removed, the quantity changes, or a campaign stops qualifying.

A useful rule of thumb is:

Whenever a cart change can affect promotion eligibility, send the current relevant cart state, not a client-side approximation of a prior promotion result.

The adapter must include every field used by configured rules. If eligibility depends on a customer’s market, channel, membership tier, or delivery country, those values must be included through the agreed data contract. Missing data commonly produces a technically successful API request but no expected reward.

---

What Talon.One does with the request

The Integration API authenticates and accepts the customer-session update. Talon.One then transforms the submitted information into an event and sends it for Rule Engine evaluation.

The Rule Engine evaluates active, applicable rules using:

• The customer-session state, including cart items and coupon codes.
• The associated customer profile, if one is attached.
• Campaign configuration, such as campaign dates, budgets, coupon rules, and rule conditions.
• Relevant application data and configured attributes.

For the example, the engine can determine that:

1. WELCOME20 is present in the request.
2. The coupon meets campaign redemption and validity conditions.
3. The cart contains SKU TJ-001, or an item matching the configured outerwear filter.
4. The jacket’s current undiscounted value is USD 120.00.
5. A 20% item-level reward has a value of USD 24.00.

The engine then returns the effects of matching rules. It does not charge the payment method, alter the price in your product catalog, create an order, or issue a refund. Those remain responsibilities of your surrounding systems.

---

Effects are decisions that your integration must interpret

For the worked example, the response could include effects with meanings such as these:

Effect type	Business meaning	Commerce integration responsibility
acceptCoupon	The submitted coupon is accepted for the current context	Mark the entered code as accepted in the cart experience
setDiscountPerItem	A named item-level discount applies to a specific cart item	Reduce the eligible jacket’s displayed and order discount amount by USD 24.00
setDiscount	A named session-level discount applies	Apply the discount against the agreed order-level base
rejectCoupon	The submitted code is not accepted	Show a suitable invalid or ineligible-code state without applying a discount

In this scenario, the customer-facing outcome is:

Line	Original value	Promotion value	Resulting value
Trail jacket	USD 120.00	USD 24.00	USD 96.00
Thermal base layers	USD 70.00	USD 0.00	USD 70.00
Water bottle	USD 20.00	USD 0.00	USD 20.00

The crucial distinction is that the setDiscountPerItem effect is not merely display data. It becomes part of the price and order representation that the commerce system eventually persists. The integration must map the effect to the correct internal line item, preserve the promotion identity, and ensure the eventual order reflects the approved discount.

At the same time, the effect is not a reason to overwrite the original catalog price. Maintain separate values:

• Original item price: USD 120.00
• Applied promotion adjustment: USD 24.00
• Effective selling price: USD 96.00

This makes recalculation, auditing, cancellations, and later returns possible.

A response with no discount effect does not necessarily mean the API call failed. It can mean no active rule qualified for the supplied context. Conversely, a successful HTTP response tells you that Talon.One processed the request; it does not prove that the commerce service successfully applied every returned effect. Those are separate outcomes that should be logged and monitored separately.

---

Re-evaluation: effects can change with the customer action

Effects describe the result for the state that was evaluated. They are not a permanent promise independent of later changes.

Suppose the shopper removes the Trail jacket but leaves the code WELCOME20 in the cart. The adapter submits the changed cart state against the same open customer session. The campaign condition requiring the jacket no longer matches, so the next response may no longer contain the item-discount effect.

This is why a correct integration does not accumulate every effect ever returned for a session. It treats the latest evaluation as the current decision for the cart and reconciles the commerce representation accordingly.

A practical trace record for each call should contain:

• Session integration ID and customer profile integration ID, if present.
• Correlation ID and channel.
• A redacted representation or hash of the submitted cart context.
• Talon.One response status and latency.
• Returned effect types and stable promotion identifiers.
• The commerce-side result of applying, rejecting, or deferring each effect.
• The resulting cart or order total.

Do not put Integration API credentials, raw authorization headers, or unnecessary personal data into these logs.

---

Open-session evaluation versus final commitment

A cart may be evaluated many times while its session is open: item added, quantity changed, coupon entered, shipping option selected, or customer identified. Those evaluations let the customer see the current promotion outcome.

Closing the session is different. The tutorial notes that closing a session can increment campaign budget counters and redeem potential coupons. It is therefore a business commitment point, not merely a front-end navigation event.

For now, retain this design principle:

Evaluate promotions while the cart is open; finalize promotion state only when the associated commercial transaction has reached the chosen commitment point.

---

Sandbox trace activity

Using a disposable sandbox customer-session ID and an existing test campaign:

1. Submit an open customer-session update containing a small cart and, if relevant, a test coupon.
2. Save the request payload with credentials removed, the response status, and the returned effects.
3. Change one eligibility fact, such as removing an eligible SKU or removing the coupon, then submit another update to the same session.
4. Compare the effects and the cart total your integration would produce. Confirm that original item prices remain unchanged in the submitted cart data.

Avoid closing a session that uses a scarce coupon or budget unless you intentionally want to test final redemption behavior.

---

Key takeaways

• A customer action becomes a Talon.One decisioning interaction when your system submits relevant state through the Integration API.
• Talon.One transforms the request into an event, evaluates active rules in the Rule Engine, and returns matching effects.
• Your integration should send the authoritative, current promotion-relevant cart and customer context—not client-calculated promotional prices.
• Effects are structured decisions such as coupon acceptance and item- or session-level discounts; commerce services must interpret and apply them.
• Re-evaluate when relevant cart or customer state changes, and reconcile the latest effects rather than accumulating historical ones.
• Closing a session can finalize campaign state, so it must align with a deliberate transaction commitment point.

Next, you will make the ownership boundary explicit: which system is authoritative for customer, cart, promotion, and fulfillment data, and what Talon.One should store versus merely evaluate.