{{ session }}

The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions.

Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information.

The session object is one of a handful of simple mechanisms to enable personalization on your site. Used well, these can be powerful tools for developers and website owners.


string object_type
Will always be "session".
true/false is_valid
Whether or not the user (or template developer) has granted permission for a session.
true/false allowed
Alias of is_valid.
string id
The unique identifier for the user's session. This will contain a value even if the user is not allowed to have a session, but the value will change on every page load.
true/false first_page
True if this is the first page load in the user's current session. Note that this will always return true if the user does not have permission for a session since we will have no "memory" of prior page loads for the current session.
date start_date
The time that the current session started (equivalent to the time that the first request was made for this session)
date end_date
The time that the current session will expire if no more requests are made. Note that sessions are extended by every request and so the end_date will also be different on every request
number num_requests
The total number of requests for the current session, including requests resulting in errors.
number num_pages
The total number of successful page requests for the current session. This is different than num_requests in that it does not include any requests which resulted in an HTTP response code other than 200. This also assumes that the current request will return a 200 response code.
number unique_pages
The total number of unique pages requested in the current session. This number could be significantly lower than num_pages if the user requests several pages multiple times.
number num_errors
The total number of errors returned in the current session. This includes any request that returns something other than a 200 response code.
list properties
The full list of custom properties that have been set for the current session. Note that this list only includes the keys, the values will have to be retrieved using the keys.
user user
The user requesting the current page.
list history
A list containing the last 100 page views for the current session.

Individual custom properties for the session may be accessed using {{ session.propertyName }} or {{ session['propertyName'] }} syntax.

You may also treat this object as a list containing all of the property names which may be iterated using a {% for %} loop. For more details, see the examples below:


{% if session.first_page %}
    <p>This is your first pageload this session!</p>
{% endif %}
{% if session.unique_pages > 10 %}
    <p>Need help finding what you're looking for? <a href="#">Try this!</a></p>
{% endif %}
{% if session.num_errors > 3 %}
    <p>We appear to be having trouble meeting your needs. Please <a href="#">contact us directly</a> so that we can assist you and fix the trouble for future visitors, or continue browsing for what you need.</p>
{% endif %}

List all custom properties for the current session:

<h4>Session Properties:</h4>
{% for property in session %} --equivalent to {% for property in session.properties %}
    <li><strong>{{property}}</strong> = {{ session[property] }}</li>
{% endfor %}

Working with specific custom properties

{% if session.is_valid %}
    {% if session.custom_property_name %}
        <p>Custom Property: {{session.custom_property_name}}</p>
    {% endif %}
    {% if session['custom_property_name_2'] %}
        <p>Custom Property 2: {{session['custom_property_name_2']}}</p>
    {% endif %}
{% endif %}

Developer Overview

Liquid Markup