Session handling

A lot of ecommerce functionality requires the use of sessions to track the users session state. This can include:

  • Items that have been added to a shopping cart
  • A users logged in status
  • User / group pricing
  • User access control

By nature API's are generally stateless - so don't maintain a session from request to request.

With the ZEST Ecommerce API, you can maintain a users session by passing a _session_token parameter with each request (in the querystring).

Establish the session

To establish a session, pass _session_token=1 to any V3 resource.

The resulting resource will return its normal result, except the root node (usually <ResultSet> for GET, or <rsp> for PUT/POST/DELETE) will now contain an additional attribute called session.

E.g. https://www.mydomain.nz/API/V3/BrowseCategory/00411?_session_token=1

<?xml version="1.0" encoding="utf-8" ?>
<ResultSet page="1" session="yjipILZBeUWxrFq" totalResults="42" totalResultsReturned="3" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://www.mysite.net/API/V3/BrowseCategory.xsd">
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00411" id="Ecommerce::Category00411">
        <!-- ETC -->
    </Category>
</ResultSet>
</xml>

Maintaining the session

Your application should then store the session attribute on the root node, and pass it back to the API with every request in that session from then on.

Session tokens will eventually time out if a decent period of time elapses between requests. If this happens, your session will automatically reset, you will lose any associated state, and a new session token will be passed back with that request. Should this happen, you will need to update your token to this new one.

To continue the session from the example above, adding product 4012 to the shopping cart, you would POSTa request to https://www.mydomain.net/API/V3/Cart?_session_token=yjipILZBeUWxrFq with the following payload:

<ResultSet>
    <CartItem>
        <sku>4012</sku>
    </CartItem>
</ResultSet>

This would return a payload containing the new cart items, including the session attribute set to the same token in its root ResultSet node.

See the Cart resource documentation for more details.