This guide shows you how to migrate from using an older Recommendations API version to using a newer one.

Migrating from v1 to v2

Changes in v2

For more information about the API, see Recommendations API v2.

Updating your code for v2

To migrate from v1 to v2, update your recommendation configurations and requests as follows:

  1. If a recommendation configuration has no parameters, define at least one parameter in the configuration, and update the requests that target the recommendation accordingly.

    # Before ("params" array in a recommendation configuration with v1)
    "params": []
    # After ("params" array in a recommendation configuration with v2)
    "params": [

  2. In requests, enclose parameters inside the params object.

    # Before (parameters in v1 requests)
      "name": "Most viewed products",
      "type": "Books"
    # After (parameters in v2 requests)
      "name": "Most viewed products",
      "params": {
        "type": "Books"

  3. Optionally, optimize your request code: