# Customer session entity

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

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

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.

There is no length limit for session IDs. Session IDs are sent as URL path parameters and must
follow URL encoding rules:

- Allowed without encoding: Letters (A–Z, a–z), digits (0–9), hyphens (`-`), underscores (`_`), periods (`.`), and tildes (`~`).
- Not allowed: Forward slashes (`/`). They break URL paths and cause request failures.
- Other special characters: Must be [URL-encoded](https://www.w3schools.com/tags/ref_urlencode.asp) before sending.

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](/docs/dev/concepts/attributes.md)
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](/docs/dev/concepts/entities/events.md#built-in-events).

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](/docs/product/campaigns/analytics/application-dashboard).
    - 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](/integration-api#tag/Customer-sessions/operation/reopenCustomerSession) 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](/docs/product/campaigns/settings/manage-campaign-budgets#coupon-limits).
  - 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.

:::tip 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.
:::

## Manage the session's state

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

- [Update customer session][updatecustomersession]
- [Return cart items](/integration-api#tag/Customer-sessions/operation/returnCartItems)

<details>
<summary>When should I update the state?</summary>

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:

- [Cancel the session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) and submit a new one.
- [Reopen the session](/integration-api#tag/Customer-sessions/operation/reopenCustomerSession).

</details>

<details>
<summary>Can I create new sessions as <code>closed</code>?</summary>

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](/docs/dev/tutorials/import-customer-data.md#step-2-import-past-customer-orders).

</details>

<details>
  <summary>Can I leave a session open permanently?</summary>
  Yes. For example, when a customer creates a cart and never proceeds to checkout.
</details>
<details>
<summary>How are sessions handled after an anonymous user has signed in?</summary>

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.
1. 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](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
for every change in the user profile to keep the user information stored in Talon.One up
to date.

</details>

<details>
<summary>When are the budget limits checked?</summary>

The [limits][limits] set in [campaign budgets][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][webhooks]
and [custom effects][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.

</details>

<details>
<summary>When are loyalty points updated and coupons redeemed?</summary>

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.

</details>

<details>
<summary>Are archived campaigns included when rules are evaluated?</summary>

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

</details>

## Related pages

- The [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint
- [Display customer sessions](/docs/product/applications/display-customer-sessions.md)

[updatecustomersession]: /integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2
[limits]: /docs/product/campaigns/settings/manage-campaign-budgets.md#limits
[budgets]: /docs/product/campaigns/settings/manage-campaign-budgets.md
[custom effects]: /docs/product/account/dev-tools/manage-custom-effects.md
[webhooks]: /docs/product/account/dev-tools/manage-webhooks.md
[archived]: /docs/product/campaigns/create-and-manage-campaigns.md#archive-a-campaign