Finalize and Send Purchase Transaction

Finalizes and sends - or simply just sends - a purchase transaction with or without an offer. The task contains a few options that together define a few different workflows for sending transactions. When a transaction is sent, it typically proceeds from client middleware - often a POS system - to SessionM. When the endpoint runs, it passes a transaction request object that contains a payload detailing the transaction, as well as any applied offer discounts that pertain to the transaction.

The task begins with a customer purchasing an item, which is then followed by the steps for sending the purchase transaction to SessionM. You can do this by following either:

  • Option 1, which describes the pure "send" workflow for a purchase made without any offers, or discounts, applied to reduce the price. It simply sends the transaction on to SessionM.

  • Option 2, which describes the "finalize and send" workflow for a purchase that includes an offer and applies its corresponding discount. This path is more complex because it offers another set of choices as to whether or not you want to lock the offer and redeem it at a later date or, instead, call for an immediate redeem. These steps then culminate in the data being sent on to SessionM.

This task also addresses how to integrate optional rule-based checks on how the purchase transaction transpires. These rules can be defined in an economy rule hierarchy governing a tier system (Option 3) or in a campaign (Option 4). They provide an excellent means for controlling the conditions that govern when transactions can reward customers with specific loyalty outcomes. For more information, you can read further on configuring rules for tier-related behaviors or campaign-based behaviors.

Send Transaction

The send transaction pattern is used to pass customer purchase data to the SessionM platform, where it will flow through the loyalty engine in near real time. This is an asynchronous flow. Transactions queue up as needed to mitigate bursts of activity. As such, be sure to set the timeout for locking an offer to a value that is greater than the absolute maximum amount of time it might take to dequeue and process the transaction.

Finalize with Lock and Redeem

The recommended implementation pattern for using the lock flow binds an offer to a transaction. Doing so prevents the offer from being applied to any other transaction until it is unlocked, or the lock timeout expires. Upon expiration, it is again available for customer use. The lock operation validates and provides a discount value for a transaction and an offer. It may be called more than once, but most use cases allow for it to be called at the end of the purchase process. The discount may change as the specified transaction changes.

The lock operation allows the optimum, or least number of calls, to serve the business logic. Once the offer is locked, the finalized transaction is all that is needed to both pass the final purchase data as well as redeem the locked offer. This eliminates the need to call either the redeem or the send (process) transaction operation.

The redeem flow is also an acceptable pattern to use when working with offers. Its primary difference from the lock operation is that it 's non-transient; once an offer is redeemed, it can not be redeemed again until it is reinstated. This is more appropriate when dealing with longer running purchase flows like e-commerce baskets, where a lock time frame might be so large that it creates a bad customer experience. (Think: Cart abandoned with an offer locked that won’t expire for days and renders the offer unavailable to the customer.)

Use the immediate redeem operation when SessionM is holding the offer but not evaluating any related rules or discount calculations.

Sequence Diagram

See the overall flow for this task below.

CUSTOMER CUSTOMER CLIENT MIDDLEWARE CLIENT MIDDLEWARE SESSIONM SESSIONM FINALIZE AND SEND PURCHASE TRANSACTION Purchase item(s) and finalize associated transaction Option 1: Without Offer Send transaction (without discounts object) Option 2: With Offer Option 2A: Lock Offer Lock offer Option 2B: Redeem Offer Immediately Redeem offer Return success message Send transaction (with discounts object) Enqueue transaction job Return success message Display success message Option 3: Economy Rules Check transaction against economy ruleset Award customer point or offer outcome Option 4: Campaign Rules Check transaction against campaign ruleset Award customer point or offer outcome

API Endpoints & Constraints

Lock and Redeem

POST /api/2.0/lock
POST /api/2.0/redeem

If passing an external user ID to SessionM and using the "ext → internal translation pattern," an additional call to get the internal SessionM user ID is required and made.

Bear in mind the following limits:

  • Maximum number of items is 1,000; maximum number of discounts is 100.
  • Limit number of calls to lock/redeem and make them only at the end of the transaction. However, changes and voids may be applied as needed.
  • Do not call lock operation after each new item is added/removed.
  • Use the unlock and reinstate to undo these operations.

Send Transaction

POST /api/2.0/send_transaction

If passing an external user ID to SessionM and using the "ext → internal translation pattern," an additional call to get the internal SessionM user ID is required and made.

Bear in mind the following limits:

  • Maximum number of items is 1,000; maximum number of discounts is 100.
  • Maximum number of payments is 100.
  • Maximum number of custom object elements is 1000 (drops in orders of magnitude as the object complexity and size increases.
  • Limit number of calls to the send transaction operation and make them only at the end of the transaction. However, changes and voids may be applied as needed.
  • Similarly, offer locking and validation should be at the end of the transaction and not after each new item is added or removed.
  • Return periods greater than 12 months will not be able to restore points upon returns.
  • Avoid using the user ID translation pattern when possible. These APIs are agnostic of the user ID, which is the source of truth for the customer. It is just as viable to pass an external ID and NOT need to translate when using the SOR pattern, where the external user ID is treated as the SessionM ID for internal processing. Note: This only works when there is one source of external ID. Multiple sources of user ID would require translation (normalization) to SessionM user ID.

Best Practices

When configuring rules to govern purchase transactions, bear in mind the following best practices:

  • Use economy rules for base program rules (rules that are not changing). These rules should utilize exclude functionality if only a few exceptions that need to be excluded from earning.

  • Ensure that purchase rules have under 50 catalog restrictions.

  • Use campaign rules for use cases that are temporary or that require certain targeting outside of tiers.