Skip to main content

Customer session entity

A customer session is a finite container of customer activity within an Application.

For example, a customer session can represent a shopping cart, or any transaction leading to a purchase.

A customer session has a unique ID. Your integration owns this ID. Any arbitrary string may be used as long as it can be used to identify the session consistently. Good examples of session IDs are order numbers, or combinations of profile ID and session start time.

A customer session can contain a variety of standard attributes, such as a shipping address or list of shopping cart items. You can also associate attributes with a session, such as a region code derived from a customer billing address.

A customer profile can have multiple customer sessions at one time.

Customer session states​

A customer session is in one of the following states and it can move to another state as follows:

Each customer session state is related to a built-in event.

A session is usually created in the open state (when a customer adds an item to the cart) or closed state (when they complete an order).

  • open: The session can be modified as many times as needed. Also:
    • If a closed session is reopened:
      • It is no longer included in the total number of closed sessions.
      • The session data is not factored into campaign analytics data.
      • The same effects are rolled back as when a closed session is cancelled.
      • Budgets are reverted in the same way as when a closed session is cancelled.
  • closed: The session cannot be modified anymore, unless it is reopened programmatically. Also:
    • The session data is factored into campaign analytics data.
    • Potential coupons are redeemed.
  • cancelled: The session had an issue or the closed or partially returned states are not valid anymore. Also:
    • The session data is not factored into campaign analytics data.
    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • The impact of the session's effects on campaign budgets is reverted, except for coupon creations.
    • Attribute value updates are not rolled back.
    • If a closed session is cancelled, it is no longer included in the total number of closed sessions.
  • partially returned: One or more cart items have been returned and the closed state is not valid anymore. Also:
    • Rollback effects undo previous effects triggered when you closed or opened the session. Per-item effects are rolled back for the returned items only.
    • The impact of the session's per-item effects on campaign budgets is reverted for the returned items only. Any other effects triggered by the session count towards the set campaign budget.
    • Attribute value updates are not rolled back.
    • If a closed session is partially returned, it is included in the total number of closed sessions.
Examples of session states
  • open: The customer adds items, referral codes, or coupons to their shopping cart.
  • closed: The customer has completed the payment step (or any final step) of the order workflow.
  • cancelled: The customer requested a full refund or the payment failed.
  • partially returned: The customer returned some of the items and expects the corresponding refund.

Managing the session's state​

As an integrator, you can set and maintain the state of your sessions using the following endpoints:

When should I update the state?

This depends on your industry and order workflow. The most important transition is when you set a session's state to closed because it updates the budgets of the campaign and applies all the effects.

For example, if you run an ecommerce website, in general, the session should be closed when your customer confirms the order but before you submit a capture request to your payment service provider. If the payment fails, you can do either of the following:

Can I create new sessions as closed?

This depends on your industry and order workflow, but it is possible. This offers performance benefits as you limit the number of requests.

There are two usual use cases:

  • If the final session content is known immediately, you can create a closed session on order confirmation.
  • Importing historical order data into Talon.One. See importing past customer orders.
Can I leave a session open permanently?
Yes. For example, when a customer creates a cart and never proceeds to checkout.
How are sessions handled after an anonymous user has signed in?

This is typically a 2-step process:

  1. When an anonymous user enters the page, create a session using the userID or an empty string as the profile ID.
  2. After the user has signed in, change the profile ID in the current session to the user's customerID.

The session is now connected to this signed-in user.

We recommend calling the Update customer profile for every change in the user profile to keep the user information stored in Talon.One up to date.

When are the budget limits checked?

The limits set in campaign budgets are checked on every session update, but the impact of the session's effects on the campaign budgets is effective only when the session is closed. However, webhooks and custom effects are included in the limits when the session is open as well.

As a result, a customer may add a coupon to their cart that might not be usable anymore by the time they checkout because other sessions closed in the meantime.

When are loyalty points updated and coupons redeemed?

Loyalty points are updated when the session is closed or cancelled. Coupons, referral codes and awarded giveaway items are redeemed when the session is closed.

All other effects, such as attribute updates and coupon/referral creations are triggered instantly on session updates unless you use a session state = closed condition in your rules.

Are archived campaigns included when rules are evaluated?

No, archived campaigns are not included in rule evaluation for performance reasons.