This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Using recommendations in emails

While prediction results from the Retail API are most commonly used in retail website placements, you can also use recommendations in email messages. Recommendations in email are usually included as part of marketing campaign email blasts, after-order emails, or abandoned cart emails.

Choosing a model type

The Recommended for You model can be a useful model for emails because it is designed to deliver recommendations in use cases where a user hasn't indicated interest in a specific item. It works best with logged-in users that have some browsing or shopping history.

The Others You May Like model is typically used as a product details page placement rather than for for email campaigns. However, you can use it for emails to recommend similar or complementary items to what a customer has recently viewed.

The Frequently Bought Together model is usually used on the "add to cart" page or "shopping cart" page, but can also be used for email.

Request requirements

In order to get relevant recommendations back, the userId field must match the user ID that is associated with a logged-in user on your website or app.

Ideally, the visitorId field should match the user's last session ID from the site. Because the last session ID isn't always recorded, a random unique identifier can also be sent as the visitorId field.

Frequently Bought Together and Others You May Like models also require product IDs in the productDetails section of the predict call. For Frequently Bought Together models, the IDs can be items from a user's most recent purchase.

Including static predictions in email

You can send static predictions by inserting data into an email template.

The predict method can be called in real time as emails go out, or the recommendations can be retrieved individually and saved either as part of an email template or in a database to be referenced later. To have the most up to date recommendations, call the predict method as close in time as possible to when the email is sent.

Calling the predict method for email

The Retail predict method takes some fields as input and returns a list of product recommendations. visitorId, userId, and id are used as input for most Recommendations AI models.

Each prediction request for a user must be made individually, using code or shell scripts.

The following is pseudocode for a predict request:

for user in userlist:
  emailTemplate.recommendations = predict(user.visitorid,user.userid,user.lastorder.id,...)
...
format email template as required

Including dynamic predictions in email

Although static predictions are simple to implement, they can become outdated more quickly than dynamic predictions. A user might not open the email for some time, and better recommendations could be available by that time. More sophisticated bulk email systems can add dynamic content by including a reference to an image in an HTML email.

The following is example HTML for an image that includes a placement reference:

<img src="https://example.com/recs/email?userid=47832&campaign=2020FALL&placement=fbt>

Getting the recommendations back can be done with a Google Cloud Function, or any server-side app that can make the prediction request. The predict results then need to be turned into an image. This can be done with a library, such as ImageMagick.

Predictions are only made for opened, viewed emails. You can also cache the results rather than creating a new image if the user opens the email again. This reduces the cost of using Recommendations AI for emails.

Because the link destination is typically hard-coded into the email, you don't necessarily know which products will be shown. Redirecting clicks to individual product pages requires additional configuration. You'll usually use a single image for all recommendations, so using an image map can help you determine which product was clicked.

Quotas

If you plan to run a large batch of predict requests over a short period of time, you should check your quotas. On your project's Quotas page, check Recommendation prediction requests per project per minute. You can request an increase by clicking Edit Quotas on the quota's details page.

We recommend implementing exponential backoff to retry requests after a delay. The service returns HTTP 429 responses if quota is exceeded.

Evaluating Results

URL tagging enables you to track and evaluate the effectiveness of campaigns. You can use Google Analytics or another analytics platform to add tracking parameters to links in emails and include that data in reports. Tag recommendation clicks from emails to filter them so that you can evaluate metrics.

If you A/B test multiple recommendations, we recommend doing so within a single campaign. All standard A/B testing guidelines for websites still apply.

What's next