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 session ID's 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 may also associate attributes to 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 sessions and customer profiles.

Customer session states​

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

Different states of customer sessions.

A session is usually created in the open state (new order) or closed state (legacy order).

  • open: The session can be modified as many times as needed.

  • closed: The session cannot be modified anymore.

    note

    A closed session can be reopened with the Reopen customer session endpoint.

    Also:

    • The session data is fed into the campaign analytics.
    • 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 removed from the campaign analytics.
    • Coupons redeemed in the session are usable again.
    • Coupons created in the session are not deleted.
    • The impact of the session's effects on campaign budgets is reverted, except for coupon creations.
    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • Attribute value updates are not rolled back.

  • 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.
    • The impact of the session's effects on campaign budgets is reverted.
    • Attribute value updates are not rolled back.
Examples
  • open: The customer is adding items, referral codes or coupons to their shopping cart.
  • closed: The customer has completed the payment step (or any last 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.

Each state is related to a built-in event.

Managing the session's state​

As an integrator, it is your responsibility to set and maintain the state of your sessions. You can do this with 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 either:

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 does Talon.One check budget limits?

Budget limit checks are done on every session update but the impact of the session's effects on the campaign budgets is effective when closing the session.

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.