Tweakwise's frontend API is a HTTP-based service which allows you to implement all of Tweakwise's features in your own storefront. The functionality of the API ranges from basic search and filtering to more novel features like guided selling.

By default, the API responds in XML. However, this can be changed by either adding format=json as a query parameter or by sending the Accept header with value application/json. Both methods are supported, but the latter (using the header) is preferred because it is the cleaner solution of the two.


Authentication takes place by means of a unique key valid only for that instance: the instance key. This key must be sent along with each request. By convention, this key is always added at the end of an endpoint's path. Take for example the endpoint with which products can be retrieved: /products. To make a request for a specific instance, the call should be /products/{instanceKey}. You can find your instance key in the app under Connectivity → Endpoints.

Example request

Now that you know the basics, you're ready to make a simple request to the frontend API! Let's use the /products endpoint to get some products and lets ask the frontend API to respond with JSON instead of XML.

curl --request GET \
     --url '{instanceKey}' \
     --header 'Accept: application/json'

Instead of using cURL, you can also go to the API reference for the /products endpoints and make a request in your browser.


Make sure to publish your instance at least once before attempting to use the frontend API. You'll get an error saying your instance key is invalid if you don't.


It's possible to use two different fronted API hosts. The benefit of using two hosts is that downtime will be reduced even further and requests will be even faster.

Frontend API hosts

There are a few technical differences between the two frontend API endpoints:

    This host is equipped with a real-time failover load balancer that automatically falls back on another data center in case of issues at one data center. This extra step in the network may increase the latency of requests.
    Via this host, the client connects directly with the closest data center and lowers the latency of requests. If there are problems at a data center, for example, hardware failure, traffic is automatically redirected to a different data center. Because this redirect is based on DNS, there may be a short interruption.

Setting up the failover

We advise using '' as the primary host and setting up a failover to ''. The networks of both of these hosts are completely separated, so we offer an extremely high uptime. We advise setting up the following mechanism:

  • A customer sends a request to the primary endpoint. If it returns a network error, you try again using the secondary endpoint.
  • If the primary endpoint remains unavailable, the secondary endpoint is used for 5 minutes.
  • After 5 minutes, the primary endpoint is attempted again. If it's available, it will continue to be used. If not, the secondary endpoint is used for 5 more minutes.
  • If there is ever a situation in which the secondary endpoint is unavailable, the primary endpoint will be attempted again.

Want to view an example in PHP?


If you'd rather use one endpoint, we advise using '' instead of ''. This makes you less dependent on any DNS delay.


The frontend API can be quite daunting with the amount of endpoints it contains. This chapter aims to provide guidance as to which endpoints are relevant to you. To do this, we'll highlight which endpoints are relevant based on the level you are on (standard, medium or recommended), which relate to additionally purchasable features (e.g. guided selling) and which endpoints can be considered optional (endpoints not necessarily needed to implement Tweakwise).


On grouped products endpoints

When reading the documentation about the endpoints below, you'll notice there are a couple of different endpoints with which products can be retrieved grouped. Note that grouped products don't work out of the box and requires you to have specified a group code for the products. You can read more about that here.

Search - level standard

Available to all customers on level standard and up is the search feature. Implementing the entire search feature can be done by implementing one of two endpoints.

Navigation search

Search/navigation-searchProvides all information needed for filtering through products for a given search term. In addition to products, also provides information like sorting options, facets, pagination, relevant search banners, and more.
Grouped search/navigation-search/groupedSame as the endpoint above, but instead the products are grouped.

Autocomplete - level standard

The autocomplete feature is available to all customers on level standard and up. To implement autocomplete, at least two endpoints need to be used. One endpoint retrieves the category, search phrase and facet suggestions, while the other endpoint fetches only the products suggestions. Together the two endpoints provide the whole autocomplete feature.

Category, search phrase and facet suggestions

Get suggestions/suggestionsGet category, search phrase, facet suggestions for a given search term.
Get suggestions grouped/suggestions/groupedSame as the endpoint above, but instead grouped products are used.

Product suggestions

Suggestion products/suggestions/productsGet product suggestions for the given search term.
Suggestion products grouped/suggestions/products/groupedSame as the endpoint above, but instead the products are grouped.


Note that there also exists the /autocomplete and /autocomplete/grouped endpoints, but these have been superseded by the suggestions endpoints above. New implementations should use these newer endpoints.

Category pages - level medium

On the medium level and up category pages become available. The implementation of these pages is quite similar to search: instead of using a search term, the navigation is retrieved for a specific category.


Navigation/navigationProvides all information needed for filtering through products within a category. In addition to products, also provides information like sorting options, facets, pagination and more.
Grouped navigation/navigation/groupedSame as the endpoint above, but instead the products are grouped.

In addition to the navigation endpoint, you might also be interested in the optional category tree endpoint to display a list of categories in your storefront which can be searched through.

Recommendations - level recommended

The recommendations feature is available to all customers on level recommended and up. Tweakwise knows two different types of recommendations: upselling & cross-selling and featured products.

There are a couple of different endpoints for upselling & cross-selling. Which one you should use depends on your specific situation. Unlike other endpoints, the grouped endpoint does relate to grouping of products, but applies grouping to the upselling & cross-selling rules itself.

For featured products only a single endpoint is needed: one with which products can be retrieved for a specific featured products configuration. Both automatic and manual featured products are handled by this endpoint.

Upselling & cross-selling

Product recommendations/recommendations/productGet all upselling & cross-selling products for a given product.
Product recommendations grouped/recommendations/groupedSame as the endpoint above, but the upselling & cross-selling rules are grouped according to their group key.
Product recommendations single rule/recommendations/productGet the upselling & cross-selling products for a given product for a specific rule.

Featured products

Featured products/recommendations/featuredGet featured products for a specific rule.

Guided selling - additional

Tweakwise has two different types of guided selling: compare and funnel. Both types have their own endpoints and therefore when implementing guided selling you'll have to decide which ones you want to support.

Guided selling

Get compare/advisorGet the resulting navigation based on the user's provided answers.
Get funnel/filterwizardGet the resulting navigation based on the user's provided answers.

Personal feed - additional

To implement the personal feed, you'll only have to use the one endpoint that returns the personal feed (a list of products) for a specific profile key.


Get personal feed/feedRetrieve a personal feed (list of products) for a specific profile.


Endpoints in this category either provide redundant functionality (it is already provided as part of another endpoint) and/or are not necessarily needed when implementing Tweakwise. Feel free to ignore these unless another endpoint previously mentioned doesn't provide the functionality you need already.

Category tree

Get category tree/categorytreeGet the category tree of your instance. Doesn't include categories for which there are no products.


Get products/productsGet a list of products based on a variety of parameters.
Get product/productGet a single product by article number.


Get facets/facetsReturns the available facets for a set of parameters. Contains the same facets as a regular navigation request.
Get facet attributes/facets/{urlkey}/attributesReturns only the attributes of a specific facet for a set of parameters.

Search banners

Get search banners/searchbannersGet a list of search banners for the given search term.


Get filter templates/catalog/templatesGet all published filter templates.
Get sorting templates/catalog/sorttemplatesGet all published sorting templates.
Get product recommendations/catalog/recommendation/productGet all published upselling & cross-selling rules.
Get product recommendation groups/catalog/recommendation/product/groupsGet all published upselling & cross-selling group keys.
Get featured recommendations/catalog/recommendation/featuredGet all published featured products configurations.
Get guided selling setups/catalog/guidedsellingGet all published guided selling configurations.
Get languages/catalog/languagesGet a list of all the languages supported for an instance. These are the languages that can be specified to various endpoints.