Recommendations

Overview

Fetch production recommendations for a single customer (personal), based on a group of products (contextual), or overall best sellers.

  • For product recommendations based on a customer, the customer can be identified using one of vuid, email, zaius_alias_*, or customer_id.

  • For recommendations based on a group of products, the products can be identified by their respective product ids. Including a customer identifier on this type of request will exclude products purchased in the last 180 days from being returned.

If no customer identifier or product ids are provided (or if no associated recommendations are available), then 7-day best sellers are returned as fallbacks.

Product records that are returned will include all the base Zaius product fields in addition to any custom fields defined in your product schema:

There will be an extra field “recommendation_type” in the returned results. The field shows which type of recommendations is being returned, of “personal”, “contextual” or “best_sellers”.

  • personal recommendations refer to products recommended to the specific customer

  • contextual recommendations refer to recommended products related to input products

  • best_sellers are calculated based on past seven days of orders (by units)

Product recommendation results will automatically be filtered using the Content Shield Filter set up for the account. Query-specific filters (criteria) can be added per the query parameters below.

https://api.zaius.com/v3/recommendations/products?{identifier}={identifier_value}&product_ids={product_id,product_id}
Get recommendations for a customer or based on a product. A more detailed workflow is included below.
Request
Response
Request
Query Parameters
{identifier}=identifier_value
optional
string
The identifier type and its value. Acceptable identifiers types include: vuid, email, zaius_alias_*, and customer_id
product_ids
optional
string
A comma-separated list of product IDs. Using the product_ids parameter will allow you to generate recommended products based on the product IDs passed in.
type
optional
string
The type of recommendation requested. Acceptable values are: personal and contextual
criteria
optional
object
Filter criteria applied to the recommendations returned. Any field on the product schema can be used to filter. See below for the filter construct.
sort_by
optional
string
Product field to sort by, which can be any base or custom field defined in your Product schema. Default sort is highest to lowest recommendation rank. Changing this will not change which products are returned, only the order in which they appear in the array.
order
optional
string
Default: "asc" Options: "asc", "desc" Order in which to sort the resulting products. Changing this will not change which products are returned, only the order in which they appear in the array. This will not change the order of products if there is no sort specified.
limit
optional
string
Integer [ 1 .. 100 ] Default: 10 Number of products to return
Response
200: OK
[
{
"product_id": "1234BLK",
"name": "Basics - Black",
"brand": "Jungle James Basics",
"sku": "1234BLK",
"upc": "042100005264",
"image_url": "https://http.cat/404",
"price": 25.99,
"parent_product_id": "1234",
"recommendation_type": "contextual"
},
{
"product_id": "1234BLU",
"name": "Basics - Blue",
"brand": "Jungle James Basics",
"sku": "1234BLU",
"upc": "042100005265",
"image_url": "https://http.cat/404",
"price": 25.99,
"parent_product_id": "1234",
"recommendation_type": "contextual"
}
]
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2019-01-02T15:53:51.522Z",
"detail": {
"message": "expected one of [vuid|customer_id|user_id|email|zaius_alias_*]."
}
}
403: Forbidden
{
"message": "Forbidden"
}

Structuring criteria filters:

{"expression":
{"operator": "AND",
"predicates":
[{"field": "_on_sale",
"datatype": "boolean",
"value": "false",
"operator": "="},
{"field": "_gender",
"datatype": "char",
"value": "mens",
"operator": "="}]
}
}
Example Request
Example Request
curl -iX GET \
'https://api.zaius.com/v3/recommendations/products?email=sample@test.com&product_id=1234,1235&limit=10' \
-H 'x-api-key: example.apiKey'
Product Recommendations Workflow