Skip to main content
Storefront API Session Handling provides functions to create and manage sessions in the storefront. This makes it possible to use user states (e.g. anonymous visit or logged-in customer) as well as session-bound data such as shopping cart and wish list consistently across multiple requests. The session is a component of the shop and is mandatory. For more information, see here.

​
Supported methods

List of all supported methods.

​
Methods for session handling

These methods take care of session handling between API and storefront: First, new session IDs are generated as the technical basis for all further API calls. If needed, complete redirect links to template pages (e.g. checkout) are built up, including handover of the current session. Optional parameters can be used to specifically control target pages (e.g. a specific checkout step or highlights), while the actual session ID is securely embedded in the link.

​
POST session/create

The following call creates a session ID.
More info: Storefront API Basics

​
Example response

​
POST session/prepareRedirect

The following call generates a complete link to a template page (e.g. checkout.htm) and carries the current session over into the storefront. Using this method makes sense if your shop is set up in a mixed way, i.e. if some parts have been created with the WEBSALE template theme and other parts with the Storefront API. The endpoint ensures that both parts use the same session. Example request that creates a complete link to the template page checkout and takes the current session along

​
Parameter overview

Example with parameters
The target page reads the value in the template:
Values in the target URL are not controlled here, but in the configuration. There are two parameters with the same name:
  • parameters in the configuration node storefrontApi.redirects is appended to the target URL as a query parameter and is available in the template like any other URL parameter, for example via $wsViews.current.paramList.
  • parameters in the request body of this endpoint is stored in the session and does not appear in the URL.
Rule of thumb: If the value should appear in the address or determine the displayed page or step, it belongs in the configuration. If it should only be known to the template, it belongs in the request body.

​
Example response

(complete URL to the target template page including session handover)
The returned link is valid for 30 seconds. After that, the session can no longer be carried over via it: in that case the shop creates a new, empty session — without an error message. The customer then sees, for example, an empty shopping cart in the order flow.Therefore, only call session/prepareRedirect immediately before the redirect, for example in the click handler of the “Go to checkout” button, not in advance when building the page.
Open the link via a real browser navigation, i.e. via window.location.href, a normal link, or a server-side redirect. A call via fetch or XMLHttpRequest is not sufficient: the customer must land on the target page so that the shop can take over the session there.

​
Error codes

Multi-step target pages. If the target template is multi-step — for example an order flow with the steps address, payment, overview, and completion — it usually selects the step to be displayed via a URL parameter. This parameter must be stored in storefrontApi.redirects so that the generated link contains it. If it is missing, the customer accesses the page without a step specification and the template shows its general notice text instead of the form. The call is answered normally with HTTP 200, no error message occurs. Which parameter your template expects should be clarified with your template contact.