Storefront API Specification¶

The Storefront API offers the endpoints needed for a site integration to Voyado Elevate. This includes queries and all unauthorized notifications. The Storefront API is a versioned API.

Latest version

Queries¶

Queries are used to request and render product listings and content by the storefront. The queries been designed to allow all Elevate driven page content to be retrieved through a single request. This enables features, such as result deduplication, and allows for other performance optimizations, such as minimizing the number of required request round trips.

The queries are divided by usage area and are built to have a natural mapping to each page type or feature area when possible. As usage of the queries affects both visitor statistics and behavior analysis, it's important that the usage of a query aligns with its intended purpose.

Non-intended query purposes

Retailers that need to use queries for a non-intended purpose should append those queries with notify=false, and contact their appointed Voyado Elevate Success Manager to follow up on correct usage.

Page configurations¶

Queries are also referred to as page requests, as they are modeled to fetch the content of a page.

Most types of page requests have a page configuration that specifies what type of content and product listings the page contains. The page configuration can either be supplied as part of the request at query time, via the Experience App or separately through Page Imports enabling merchandising of pages.

For example, a regular landing page request by default includes a single faceted product listing. When requesting a Landing Page for an intermediate category page, the page configuration could specify to additionally include one or more recommendation listings.

Page requests can be made either as a GET request, supporting Page Integrations, or as a POST request with a page configuration supplied in the body.

Conflicting page configurations

Any conflicting configuration made through a Page Integration always supersedes the supplied page configuration in a request body.

Notifications¶

Notifications are used to share visitor behavior with Elevate as well as for reporting and behavior analysis.

Notifications are a vital part of evaluating real time relevance and should always be supplied at the time of user interaction and implemented to the fullest extent possible.

Mandatory¶

Click and add to cart notifications are essential and must be supplied. Payments are also mandatory, but are a part of the Admin API as they require authorization.

Situational¶

Add and remove favorite notifications are required when the Favorites recommendation is to be used.

Optional¶

End notifications are optional, and can be used to terminate personalization upon a visitor logging out.

Response objects¶

Each page type has a set of defined response objects, found in the API specification. Some response objects apply to multiple pages and reoccur within different types of responses, such as product groups. When dealing with response objects, always consider the following:

Always account for the possibility that lists may be empty, unless explicitly specified otherwise.
An attribute that is returned as null from Elevate is automatically removed from the response object.
When using templates to define the response objects, attributes may be added or removed compared to this documentation

Product groups¶

Only the first product in the products array matches the current context. The other products can be used to portray thumbnails and swatches to inform the visitor of additional similar options. If multiple products within the same product group match a result, they will be returned as separate product groups with each product positioned as the first item in the products array respectively. If the number of products returned per group has been limited, then remaining will say how many products were not included.

There are different types of facets that can be returned, each supporting facet specific details to enable facet specific rendering, such as a range of values for sliders, or a boolean checkbox. All facets have some shared properties, but depending on facet type, unique additional properties apply.

The navigation object consists of breadcrumbs and a tree of navigation nodes, where the returned object is the root of the tree. The format of the navigation tree request response differs slightly from the standard navigation format of the search pages and category and landing pages responses.