Skip to content


The Apptus eSales 4 API enables server and client side integrations through HTTP queries that returns raw JSON data, enabling unlimited flexibility and customization. The API handles the communication with the Apptus eSales Cluster and includes both automatic load balancing and fail over.

The API has three main integration areas: Imports to import products and content into eSales, Queries to retrieve results, and Notifications to share visitor behavior with eSales for reporting and behavior analysis.

A JavaScript Library, including TypeScript models, is available to facilitate client side integrations to eSales 4 using the HTTP API.

Getting started

To get started with the eSales 4 API integration, a few prerequirements must be met.

Once these have been met, read through Tips and best practices and continue with integrating the queries and notifications.

Origin host

The origin host is part of the security settings for a cluster. It specifies what domain Ajax requests to the cluster are allowed to originate from. This setup is part of the customer onboarding process and performed by Apptus, with information provided by the retailer.

Default configuration allows Ajax requests originating from all origins but a restricted access to the API is recommended. The following information is needed from the customer to configure the origin host correctly:

  • Protocols (HTTP/HTTPS)
  • Domains (subdomains)
  • Ports (80, 443)

Connection requirements

Tips and best practices


A general rule of thumb is to never cache eSales generated responses. Caching prevents personalization and can cause notifications to be erroneous due to cached tickets. This does not include static data and resources such as images, which can be cached.

Request parameters

Query parameters are case sensitive.

Request headers


All responses that are applicable from eSales will be compressed with gzip if the request header Accept-Encoding has the value gzip, i.e. the eSales 4 HTTP API supports gzip encoded responses. For performance reasons, it is recommended to always use compressed responses.

User agents

For internal tracking, helpful for troubleshooting, as well as for potential future features, it is recommended to provide a User-Agent header in the requests to the HTTP API.

Browser preflight requests

To support large requests with unique page configurations, queries can be performed through HTTP POST. Queries return JSON objects as responses, but requests in browsers with application/json as content-type automatically triggers a preflight request. To avoid this, text/plain is supported as content-type and can be used in client side integrations.

Postman collection

Page requests can be tested by downloading the eSales 4 Postman collection for use with the tool Postman. Note that the {cluster-id} in the example queries must be changed to the correct cluster id.

Last update: March 25, 2022
Back to top

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.