Best Practices for Recommendation API

  • Published on Feb 4, 2026
  • 1 minute(s) read
Prev Next

Category List Format

When filtering by categories, pass categoryList as a URL-encoded JSON array:

categoryList=["shoes","boots"]

In cURL, encode the brackets properly:

?categoryList=%5B%22shoes%22%2C%22boots%22%5D

Hyperpersonalization (hp)

Enable hyperpersonalization by adding hp=1 or hp=true:

?userId=user123&hp=1

This uses customer affinities to further personalize results.

Mixed Strategy

Combine multiple recommendation algorithms in a single request to get diverse results.

GET /mixed?partnerName=X&locale=en_US&userId=user1&currency=USD&strategy=[...]

Strategy array format:

[
  {"recommendationType": "ub", "size": 4},
  {"recommendationType": "vtv", "size": 3, "productId": "prod1"},
  {"recommendationType": "mvop", "size": 3, "filters": ["\[category\]\[=\]\[shoes\]"]}
]

Available types: ub, ue, vtv, btb, cp, sp, mvoc, mvop, mpoc, mpop, mpol, naoc, naop, tpoc, tpop, mvpoc, mvpop, mm, hdop, hdoc, rvp, lpt

Each strategy specifies its algorithm type, the number of products to return, and, optionally, its own filters.

Manual Merchandising in Mixed

Use mm to include specific products you want to promote. The productId field is required.

{"recommendationType": "mm", "size": 3, "productId": "featured1,featured2,featured3"}

Full example:

GET /mixed?partnerName=X&locale=en_US&currency=TRY&strategy=[{"recommendationType":"ub","size":5},{"recommendationType":"mm","size":3,"productId":"promo1,promo2,promo3"},{"recommendationType":"mvop","size":2}]

  • Pass product IDs as comma-separated values.

  • Products are returned in the order you specify.

  • Only in-stock products are returned.

Multiple Item IDs in Item-Based Algorithms

Get recommendations based on multiple products at once by passing comma-separated IDs:

GET /vtv?partnerName=X&locale=en_US&productId=item1,item2,item3&size=10&currency=USD

Supported endpoints are /vtv, /btb, /cp, /sp. It is useful when you want recommendations based on multiple items in a cart or wishlist.

Group Products

Include product variants (e.g., different sizes/colors) in the response using getGroupProducts.

GET /ub?partnerName=X&locale=en_US&userId=user1&getGroupProducts=true&groupProductsFields=price,in_stock,product_attributes.color

Parameters

  • getGroupProducts=true — Enable variant products in response

  • groupProductsFields — Additional fields to include (comma-separated)

Response structure

{
  "item_id": "shoe-blue-m",
  "group_products": [
    {"item_id": "shoe-blue-s", "price": {"USD": 99}, "in_stock": 1},
    {"item_id": "shoe-blue-l", "price": {"USD": 99}, "in_stock": 1}
  ]
}

Variants are grouped by groupcode. You can request nested fields, such as product_attributes.color.

Filter Chaining with asteriks (*)

To combine multiple filters with AND logic, use *.  Here is an example of applying multiple filters: 

GET 
...&filter=[category][=][shoes]*[brand][=][nike]*[price][<][100]

Related articles