# About the Recommendations Service Plugin

<blockquote class="important">

__Important:__ 
When developing websites or building apps with Blocks, use [Velo service plugins](fallback::https://dev.wix.com/docs/velo/events-service-plugins/about-events-service-plugins-and-the-sdk).

</blockquote>

By implementing the Recommendations Service Plugin, you can integrate your service with Wix to provide advanced recommendation algorithms that allow Wix merchants to provide tailored product recommendations to their customers.

The integration process involves [creating an app](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/about-developing-apps) and configuring the Recommendations [service plugin extension](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions).

With this service plugin, you can design your app to deliver tailored recommendations across various content types, such as products, services, events, or any combination the above. For example, you can:
+ Recommend products frequently bought together with the selected one.
+ Recommend blog posts related to the one currently being viewed.
+ Suggest a yoga mat when a yoga class service is booked.
+ Recommend popcorn when a ticket for a movie event is purchased.

When your app implementing the Recommendations service plugin is installed on a Wix site, the recommendation algorithms it supports become accessible through the [Recommendations API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::4d9c288b-bebc-4735-aaa8-4ce311c4a76dslug::introduction*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/recommendations/introduction). 


## Before you begin

It’s important to note the following points before starting to code:

- This service plugin isn't yet supported by the [CLI](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/about-the-wix-cli-for-apps).

- Algorithms select items to recommend from their supported catalogs. The apps providing these catalogs must be installed on the Wix site before you can start using the Recommendations service plugin on this site.


## Get started

To enable Wix to communicate with your app:

1. Select your app from the [Custom Apps page](fallback::https://manage.wix.com/studio/custom-apps) in your Wix Studio workspace. 
1. Go to [**Extensions**](fallback::https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fextensions) and click **+ Create Extension**.
1. In the **Choose the extension you want to create** modal, use the search bar and look for **Recommendations**. Then select **Ecom Recommendations Provider** and click **Create**.
1. In the JSON editor, create the extension’s configuration file, ensuring that all required fields outlined in the table below are included.


### Configuration file fields

| Name | Type | Description |
|----------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `deploymentUri` | string | Required. Base URI for your service's methods. Wix appends the method path to the base URI. For example, to call the Get Recommendations method at `https://my-recommendation.com/v1/get-recommendations`, the base URI you provide here is `https://my-recommendation.com/`.|
| `catalogAppIds` | Array <string> | Required. App IDs of supported catalogs. The following are Wix apps that provide catalogs and their app IDs: Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` |
| `supportedAlgorithms`| Array <object> | Required. Recommendation algorithms implemented by the app. See the table below for details on the structure of the supportedAlgorithms object. |
| `componentName` | string | Required. A unique name for this component. This is an internal name that will only appear in the app dashboard. |
 
### `supportedAlgorithms` properties

| Property | Type | Description |
|-----------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reserved` | int | Reserved field with a value of 1. |
| `name` | string | Required. Algorithm name. This value is not translatable. |
| `description` | string | Required. 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. |
| `additionalInfo`| google.protobuf.StringValue | 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. |
| `algorithmType`| enum | 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. |
| `algorithmId` | string | Required. 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. |

 
 The following is an example of a valid config file:
 
 ```json
 {
 "deploymentUri": "https://my-recommendation.com/",
 "catalogAppIds": ["c567afb8-ac2c-4888-a90c-94933066ae6a"],
 "supportedAlgorithms": [
 {
 "algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
 "name": "Frequently bought together",
 "description": "Products frequently bought together with selected one",
 "algorithmType": "RELATED_ITEMS"
 },
 {
 "algorithmId": "97f48eb2-4d42-4296-b620-13862dd0353e",
 "name": "Personalized recommendations",
 "description": "Personalized recommendations based on user's behavior",
 "additionalInfo": "Works best when user has a history of interactions with the site",
 "algorithmType": "GLOBAL"
 }
 ],
 "componentName": "MyRecommendations"
 }
 ```
1. Click **Save**.
1. Click [**Test Your App**](portalId::63e3acd8-2a9c-421d-8f92-d02930eeb59eresourceId::045e3c87-858e-41c1-998f-4c54a7b003a8*fallback::https://dev.wix.com/docs/build-apps/launch-your-app/app-submission/test-your-app-on-a-premium-site), and then check that the recommendations are working as intended. 

## Terminology

+ __Supported catalogs__: The types of items that can be recommended through your service. This may include products, services, events, blog posts, and other content types.
+ __Recommendation algorithm__: The logic used to generate recommendations. For example, logic that determines products frequently bought together, shows frequently watched together, new arrivals, or personalized recommendations.
+ __Recommendation__: A curated list of items generated by the algorithm. For example, a list of products frequently bought with a selected item.


## See also
+ [About Service Plugin Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)
+ [Add a Self-hosted Service Plugin With the SDK](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk)
+ [Add Self-hosted Service Plugin Extensions with REST](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest)

# Recommendations Provider: Sample Flows

This article presents a sample flow your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your Recommendations integration.

## Provide recommendation algorithms that Wix users can use to recommend products

In this flow, a Wix user selects a recommendation algorithm provided by your app, and adds a "Related Products" widget to display the recommendations. Wix calls the Recommendations service plugin to get a list of items recommended by the algorithm, which are then sent to the widget.

Before implementing this flow, configure your app, so it can communicate with your Recommendations service plugin implementation.

>**Note:** Currently, only the Online Stores app has a user interface (UI) that supports recommendations. To work with the Online Stores app, ensure that you include `catalogAppIds: ["215238eb-22a5-4c36-9e7b-e7c08025e04e"]` when configuring your Ecom Recommendations Provider extension in your app's dashboard. 
> 
>Alternatively, you can implement your own custom UI to display recommendations by leveraging one of [Wix’s Development Frameworks](fallback::https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks) and the [Recommendations API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::4d9c288b-bebc-4735-aaa8-4ce311c4a76dslug::introduction*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/recommendations/introduction).

### Customize recommendations in the Wix editor

1. The Wix user installs and authorizes your app to provide recommendation algorithms.
1. The Wix user navigates to the Wix Editor and adds a **Related Products** widget to their products page by selecting **Add Elements → Store → Related Products**.
1. The Wix user clicks the **Settings** button on the widget. Your recommendation algorithms are shown in the dropdown alongside other algorithms provided by the Wix Stores app. Algorithms with the `algorithmType` of `RELATED_ITEMS` are listed under the "Related Products" section. 

### Recommend related products on a store page

1. A site visitor navigates to a page with the Related Products widget.
1. Wix sends a [Get Recommendations](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::c17a30d0-4209-4a7f-94e6-297a79ce15c4slug::get-recommendations*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/recommendations-service-plugin/get-recommendations) service plugin request to your app. The payload includes the `algorithmId` of the selected algorithm. If the widget is installed on a products page, the `items` field is populated with the product's ID as `catalogItemId` and the Wix Stores app ID as `appId`: 

    ```json
    {
      "algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
      "items": [
        {
          "catalogItemId": "ec7914e8-208b-0069-5850-1a965643508d",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
        }
      ]
    }
    ```
   On any other page, the `items` field is empty.
   
1. Your app responds with a list of recommendations.

    Example of a successful response from your app:
    
    ```json
    {
       "recommendationPerAlgorithm": [
        {
          "algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
          "recommendedItems": [
            {
              "catalogItemId": "1ce6198f-5fad-5ac9-5b36-ecb2175929ef",
              "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
            },
            {
              "catalogItemId": "58a7ab15-5c65-d836-7934-86f78b17996b",
              "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
            }
          ]
        }
      ]
    }
    ```
    
1. The site displays the recommended products in the widget based on the IDs of the products returned in your response.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Extend Websites with SDK

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

GraphQL (Alpha)

Used for grouping line items. Sent when an item is added to a cart, checkout, or order.

ID of the app providing the catalog.

You can get your app's ID from its page in the [app dashboard](https://dev.wix.com/dc3/my-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"`

appId

ID of the item within the catalog it belongs to.

catalogItemId

Additional item details in `key:value` pairs.

Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items.

For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration)
or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction).

options

CatalogReference

values

ListValue

NullValue

value

StringValue

fields

Struct

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

this message is not directly used by any service,
it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform.
e.g. SPIs, event-handlers, etc..
NOTE: this context object MUST be provided as the last argument in each Velo method signature.

Example:
```typescript
export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) {
...
}
```

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

currency

An object that describes the identity that triggered this request.

instanceId

A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

Context

identityType

IdentificationData

IdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

This method retrieves an array containing the lists of recommended items returned by each algorithm. Items must be selected from catalogs in Wix apps installed on the site.

If a requested recommendation algorithm's type is `RELATED_ITEMS` then the `items` field is included in the request. The response should contain items related to those submitted.
How the related items are selected depends on the recommendation algorithms used. For example, items can be in the same category, or can be frequently bought or watched together.

One or more of the requested `algorithm_ids` aren't supported by the provider. Check the provider's `supported_algorithms` configuration for valid algorithm IDs.

AlgorithmNotSupportedWixError

AlgorithmNotSupportedError

One or more items are from catalogs that aren't supported by the provider. Only provide items from catalogs listed in the provider's `catalog_app_ids` configuration.

ItemAppIdNotSupportedWixError

ItemAppIdNotSupportedError

GetRecommendations

The JSON object below defines the configuration for this service plugin extension. How you supply values depends on the framework you’re using:

+ **Self-hosted apps:** After adding a service plugin extension to your app in the app dashboard, provide configuration details in your extension's page. Learn more about how to add and configure a self-hosted service plugin extension with [REST](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest) or the [SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk).
+ **CLI apps:** Customize the configuration in your extension's [`<extension-name>.extension.ts`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend/service-plugins/service-plugin-extension-files-and-code#service-plugin-builder) file.

Recommendations Provider

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

nanos

seconds

GoogleProtoDuration

latitude

longitude

Location

name

number

StreetAddress

AlgorithmNotSupportedWixWixError

ItemAppIdNotSupportedWixWixError

import { recommendationsProvider } from '@wix/ecom/service-plugins';

async function getRecommendations(request,metadata) {
  const response = await recommendationsProvider.getRecommendations(request,metadata);
};

getRecommendations

import { recommendationsProvider } from '@wix/ecom/service-plugins';
import { auth } from '@wix/essentials';

async function myGetRecommendationsMethod(request,metadata) {
  const elevatedGetRecommendations = auth.elevate(recommendationsProvider.getRecommendations);
  const response = await elevatedGetRecommendations(request,metadata);
}

getRecommendations (with elevated permissions)

import { createClient } from '@wix/sdk';
import { recommendationsProvider } from '@wix/ecom/service-plugins';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { recommendationsProvider },
  // Include the auth strategy and host as relevant
});


async function getRecommendations(request,metadata) {
  const response = await myWixClient.recommendationsProvider.getRecommendations(request,metadata);
};

Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

Extension Config