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
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 'https://gateway.tweakwisenavigator.com/products/{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.
Endpoints
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).
- Search - level standard
- Autocomplete - level medium
- Category pages - level medium
- Recommendations - level recommended
- Guided selling - additional
- Personal feed - additional
- Optional
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
Name | Endpoint | Description |
---|---|---|
Search | /navigation-search | Provides 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/grouped | Same 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
Name | Endpoint | Description |
---|---|---|
Get suggestions | /suggestions | Get category, search phrase, facet suggestions for a given search term. |
Get suggestions grouped | /suggestions/grouped | Same as the endpoint above, but instead grouped products are used. |
Product suggestions
Name | Endpoint | Description |
---|---|---|
Suggestion products | /suggestions/products | Get product suggestions for the given search term. |
Suggestion products grouped | /suggestions/products/grouped | Same 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
Name | Endpoint | Description |
---|---|---|
Navigation | /navigation | Provides 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/grouped | Same 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
Name | Endpoint | Description |
---|---|---|
Product recommendations | /recommendations/product | Get all upselling & cross-selling products for a given product. |
Product recommendations grouped | /recommendations/grouped | Same as the endpoint above, but the upselling & cross-selling rules are grouped according to their group key. |
Product recommendations single rule | /recommendations/product | Get the upselling & cross-selling products for a given product for a specific rule. |
Featured products
Name | Endpoint | Description |
---|---|---|
Featured products | /recommendations/featured | Get 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
Name | Endpoint | Description |
---|---|---|
Get compare | /advisor | Get the resulting navigation based on the user's provided answers. |
Get funnel | /filterwizard | Get 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.
Feed
Name | Endpoint | Description |
---|---|---|
Get personal feed | /feed | Retrieve a personal feed (list of products) for a specific profile. |
Optional
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
Name | Endpoint | Description |
---|---|---|
Get category tree | /categorytree | Get the category tree of your instance. Doesn't include categories for which there are no products. |
Products
Facets
Name | Endpoint | Description |
---|---|---|
Get facets | /facets | Returns the available facets for a set of parameters. Contains the same facets as a regular navigation request. |
Get facet attributes | /facets/{urlkey}/attributes | Returns only the attributes of a specific facet for a set of parameters. |
Search banners
Name | Endpoint | Description |
---|---|---|
Get search banners | /searchbanners | Get a list of search banners for the given search term. |
Catalog
Name | Endpoint | Description |
---|---|---|
Get filter templates | /catalog/templates | Get all published filter templates. |
Get sorting templates | /catalog/sorttemplates | Get all published sorting templates. |
Get product recommendations | /catalog/recommendation/product | Get all published upselling & cross-selling rules. |
Get product recommendation groups | /catalog/recommendation/product/groups | Get all published upselling & cross-selling group keys. |
Get featured recommendations | /catalog/recommendation/featured | Get all published featured products configurations. |
Get guided selling setups | /catalog/guidedselling | Get all published guided selling configurations. |
Get languages | /catalog/languages | Get a list of all the languages supported for an instance. These are the languages that can be specified to various endpoints. |