Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

A list of algorithms checked in a specific order determined by their `appID` and their position in the `algorithms` array.
See the method description for more information.

If no algorithm is able to return at least `minimumRecommendedItems` items, an empty array is returned.

algorithms

options

GetRecommendationOptions

Returns a recommendation object containing a list of items to recommend to the customer.

`getRecommendation()` determines which items to recommend based on the given recommendation algorithms.

`getRecommendation()` doesn’t run the algorithms. It calls the installed apps that provide them.

Apps may provide algorithms for use with their own catalogs, or for use with catalogs from other apps.
For example, Wix Stores provides algorithms that can only be used on its own catalogs.
To run an algorithm, the app providing it must be installed, and an app providing a supported catalog must be installed.
For more information and to see which algorithms are available on your site or project, call [`listAvailableAlgorithms()`](#listavailablealgorithms).

`getRecommendation()` operates as follows:
1. `getRecommendation()` receives as input a list of algorithms as an array. These algorithms can be provided by different apps and can apply to different catalogs.
2. `getRecommendation()` calls the app that corresponds to the `appId` of the first algorithm in the list of algorithms. It passes that algorithm’s ID and the IDs of any subsequent algorithms in the array for the same app.
3. The app runs the algorithms.
4. `getRecommendation()` returns items recommendations from the first algorithm (according to its position in the `algorithms` array) that meets the minimum number of recommendations. At that point `getRecommendation()` stops calling other apps.
5. If none of the algorithms run by the first app meet the minimum recommended items, `getRecommendation()` finds the next algorithm in the array with a new `appId` (an ID of an app that has not yet been called), and repeats the process.
6. If no algorithms in the `algorithms` array recommend at least the minimum recommended items, `getRecommendation()` returns an empty array.

/**************************************
 * Backend code - recommendations.web.js *
 *************************************/
import { Permissions, webMethod } from 'wix-web-module';
import { recommendations } from 'wix-ecom-backend';
  
export const getRecommendation = webMethod(Permissions.Anyone, async (algorithms, options) => {
  try {
    const result = await recommendations.getRecommendation(algorithms, options);

    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/*************
 * Page code *
 ************/


import { getRecommendation } from 'backend/recommendations.web';

$w.onReady(async function () {
  let algorithm = {
    appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',
    id: '68ebce04-b96a-4c52-9329-08fc9d8c1253'
  };
  let item = {
	appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',
	catalogItemId: '11e2ffb7-2520-3c21-051e-1f05486b9061'
  };
  let options = {
	items: [item],
	minimumRecommendedItems: 1
  }
  let recommendations = await getRecommendation([algorithm], options);
  console.log(recommendations);
});


Get recommendation with algorithms and options objects 

getRecommendation

GetRecommendationResponse

Returns a list of recommendation algorithms that can be used on your Wix site or project. These algorithms can be used with [`getRecommendation()`](#getRecommendation) to provide item recommendations to the customer.

Algorithms are run by the apps that provide them, and can only be used on catalogs they support. Apps may provide algorithms for use with their own catalogs and/or catalogs from other apps.

The app which provides an algorithm is referenced by that algorithm’s `appId`. The apps whose catalogs are supported by an algorithm are referenced by the IDs in that algorithm’s `catalogAppIds` array.


For an algorithm to be considered “Available” and returned in this method’s response, the algorithm must meet the following conditions:
1. The algorithm’s `appId` must match the ID of an installed Wix app.
2. At least 1 of the IDs in `catalogAppIds` must match the ID of an installed Wix app.

Wix app IDs are [listed here](https://dev.wix.com/api/rest/getting-started/wix-business-solutions#getting-started_wix-business-solutions_about-wix-business-solutions).

import { recommendations } from 'wix-ecom-backend';

async function listAvailableAlgorithms() {
  try {
    const result = await recommendations.listAvailableAlgorithms();
    return result;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}


listAvailableAlgorithms example

import { recommendations } from 'wix-ecom-backend';
import { webMethod, Permissions } from 'wix-web-module';

export const listAvailableAlgorithms = webMethod(
  Permissions.Anyone,
  async () => {
    try {
      const result = await recommendations.listAvailableAlgorithms();
      return result;
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
);


listAvailableAlgorithms example for exporting from backend code

listAvailableAlgorithms

ListAvailableAlgorithmsResponse

# Introduction

&nbsp;

<div style="background-color: #FEF1D1; padding: 18px 24px; border-radius: 6px; border: 1px solid #FDB10C; box-sizing: border-box; display: inline-block">
Developer Preview
 
APIs in <a href="https://www.wix.com/velo/reference/api-overview/developer-preview"> Developer Preview</a> are subject to change and are not intended for use in production. <a href="mailto:velo-preview-feedback@wix.com">Send us</a> your suggestions for improving these functions. Your feedback is valuable to us.
</div>

&nbsp;

The Recommendations API allows you to promote and recommend items to your customers. You can get item recommendations from catalogs on your site using algorithms provided by apps. 

>**Note:** Currently, the Recommendations API is for use with Wix Stores only.

With the Recommendations API, you can:
* Get a [list of algorithms](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/listavailablealgorithms) available for use on your site.
* Get a [list of recommended items](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/getrecommendation) suggested by a given algorithm.



## Algorithms

Algorithms are programs that identify and return a set of item recommendations based on a catalog. There are different types of algorithms, identified by their `algorithmType` that calculate different kinds of recommendations. For example, Algorithms with the `RELATED_ITEMS` `algorithmType` also take a list of items as input and use those to calculate recommendations.

For example, Wix Stores provides the following algorithms:

| Name | Description | Algorithm Type |
|------------------------------|------------------------------------------------------------------------------------|-----------------|
| “From the same categories” | Returns items that share the most categories with items in the list provided. | `RELATED_ITEMS` |
| “Frequently bought together” | Returns items that are frequently bought together with the first item in the list provided. | `RELATED_ITEMS` |
| “Frequently viewed together” | Returns items that are frequently viewed together with the first item in the list provided. | `RELATED_ITEMS` |
| “Best sellers” | Returns the items from the catalog with the highest number of sales. | `GLOBAL` |



<blockquote class="tip">
 
__Tip:__
If you want to display item recommendations on your site, you can use the Wix Stores [“Slider Product Gallery”](https://support.wix.com/en/article/wix-stores-adding-store-elements#slider-product-gallery) and [“Related Products”](https://support.wix.com/en/article/wix-stores-adding-a-related-products-gallery) elements. These elements use Recommendations API functionality without the need for manual coding. In these elements' settings, you can choose which algorithm to use from among those available on your site.

On your Product, Cart, and Thankyou pages you can use `RELATED_ITEMS` type algorithms to get recommendations related to the product/s shown on the page.
On other pages, you can get recommendations from `GLOBAL` type algorithms.

</blockquote>


## Before you begin
* You must have a Wix app that provides algorithms installed on your site, and you must have a Wix app whose catalogs are supported by those algorithms installed on your site. For more information see [`listAvailableAlgorithms()`](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/listavailablealgorithms). Currently, the only app providing algorithms and their supported catalogs is Wix Stores.
* No caching is implemented, so repeat calls take the same time to complete as the first call.

We To use the Recommendations API,
import `{ recommendations }` from `wix-ecom-backend`:

```js
import { recommendations } from 'wix-ecom-backend';
```

## Use cases
[Send emails to customers recommending related products.](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/sample-flow)

## Terminology
* **Catalog:** A set of products or services available for purchase in a Wix app. For example, a set of products in Wix Stores.
* **Algorithm:** A program implemented by a Wix app, such as Wix Stores, which returns a list of item recommendations.


## Permissions information


Functions in the Recommendations API are restricted and only run if you elevate permissions using the `wix-auth` [`elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.


<blockquote class='warning'>
Warning: Elevating a function allows it to be called by any site visitor. Exercise caution to prevent security vulnerabilities.
</blockquote>

# Sample Flow
This article shares a possible use case your site could support, as well as an example flow that could support the use case. You're certainly not limited to this use case, but it may be a helpful jumping-off point as you plan your app's implementation.


## Send emails to customers recommending related products 
To send emails to customers with item recommendations based on their most recent purchases from your Wix store, follow this basic flow:

1. [Query the Stores/Orders collection](https://www.wix.com/velo/reference/wix-stores-backend/%22orders%22-collection-fields#wix-stores-backend_%22orders%22-collection-fields_orders-collection-fields) on your site, using appropriate [filtering](https://www.wix.com/velo/reference/wix-data/filter) to obtain the most recent order by a customer (identified by their contact or member ID).
2. Record the `catalogItemId` from the first `lineItem`.
3. Call [`listAvailableAlgorithms()`](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/listavailablealgorithms) in the Recommendations API to get the `algorithmId` of the "Frequently bought together" algorithm.
4. Call [`getRecommendation()`](https://www.wix.com/velo/reference/wix-ecom-backend/recommendations/getrecommendation) in the Recommendations API with the `catalogItemId` from step 2 and the `algorithmId` from step 3. Use the Wix Stores app ID (`215238eb-22a5-4c36-9e7b-e7c08025e04e`) in the algorithm object.
5. For each item in the object returned by `getRecommendation()`, call [`getProduct()`](https://www.wix.com/velo/reference/wix-stores-v2/products/getproduct) in the Wix Stores Products API using the recommended item’s `catalogItemId`.
6. Using the information in the responses from `getProduct()`, generate an email with the relevant information from each item and send it to the customer.
7. Repeat steps 1-6 for each customer.



velo-deps_wix-ecom-backend_recommendations

Algorithm

Algorithm ID defined by the app providing the algorithm.

string

App ID of the Wix or 3rd-party app providing the algorithm.

Wix app IDs are <a href="https://dev.wix.com/api/rest/getting-started/wix-business-solutions#getting-started_wix-business-solutions_about-wix-business-solutions" target="_blank">listed here</a>.

appId

AlgorithmConfig

Algorithm ID. This must be unique for a specific app but does not have to be unique across all apps on the site or in the project.

A supplemental `description`. It can be used to help break up and organize information. You can, for example, display this information as a tooltip or as an additional section that is collapsed by default.

additionalInfo

Algorithms may have the following types:
* `RELATED_ITEMS` - This type of algorithm provides recommendations based on 1 or more other provided items. For example, when an item is added to a cart, the algorithm can suggest other items frequently bought together with that item.
* `GLOBAL` - This type of algorithm provides general recommendations based on site or project statistics. For example, bestsellers or new arrivals.

algorithmType

AlgorithmType

Algorithm description. This describes how the algorithm works and if it has any limitations regarding site content, number of items in the catalog, site traffic, and so on. This value is not translatable.

description

Algorithm name. This value is not translatable.

name

AlgorithmInfo

The app ID of the application providing the algorithm.

Wix app IDs are <a href="https://dev.wix.com/api/rest/getting-started/wix-business-solutions#getting-started_wix-business-solutions_about-wix-business-solutions" target="_blank">listed here</a>.

App IDs of catalogs to which the algorithm can be applied.

Wix app IDs are <a href="https://dev.wix.com/api/rest/getting-started/wix-business-solutions#getting-started_wix-business-solutions_about-wix-business-solutions" target="_blank">listed here</a>.

catalogAppIds

config

CatalogReference

ID of the app providing the catalog.

You can get your app's ID from its page in the [Wix Dev Center](https://dev.wix.com/apps).

For items from Wix catalogs, the following values always apply:
+ Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`
+ Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`
+ Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"`

ID of the item within the catalog it belongs to.

catalogItemId

Additional item details in key:value pairs. Use this optional field to provide more specificity with item selection. The `options` field values differ depending on which catalog is providing the items.

For products and variants from a Wix Stores catalog, learn more about [eCommerce integration](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/e-commerce-integration).

Algorithms available for use on your Wix site or project. See the method description for more information.

listAvailableAlgorithms( )

Permission Scopes