Recommendation configuration ID.

Site ID.

Recommendation configuration name.

The name must be unique within the site. The platform validates the name when saving the configuration and throws an error if the name is not unique.

The default value is a randomly generated universally unique identifier (UUID). It is recommended that you change the name to something descriptive and useful for users.

Description of the recommendation configuration. Use the description to explain what sort of recommendation the configuration generates.

The default value is Newly created recommendation.

Recommendation type.

The type defines the algorithm that the platform uses to generate the recommendation.

The possible values for the built-in algorithms are:

• bundle_converted
• bundle_viewed
• bundle_viewed_converted
• most_converted
• most_viewed

The default value is most_viewed.

For more information about the algorithms, see Supported recommendation algorithms.

Current status of recommendation data generation.

The possible values are (in process order):

• new: Recommendation data generation has yet to be scheduled.
• scheduled: Recommendation data generation has been scheduled. Depending on how many other recommendation configurations are in the queue, it might take anywhere from a fraction of a second to several minutes before the data generation starts.
• started: Recommendation data is being generated.
• success: Recommendation data was successfully generated.
• failure: Recommendation data generation failed.

The default value is new.

Total number of seconds it took to generate the recommendation data.

How often the recommendation data is to be regenerated.

The possible values are:

• 0m: Recommendation data is not automatically regenerated. You must manually generate the data.
• 15m: 15 minutes
• 1h: 1 hour
• 1d: 1 day (24 hours)

The default value is 15m.

If you enter a value not listed above and save the configuration, the platform ignores the value and retains the existing one (default value unless previously saved with another valid value).

The regeneration point in time is calculated based on the last time the data was generated (either automatically or manually). For example:

• If the frequency is 15 minutes, and the data is generated at 10:15, the data is next generated at 10:30.
• If the frequency is 1 day, and the data is generated at 10:15, the data is next generated at 10:15 the following day.

It is recommended that you set frequency based on hours as follows:

Amount of usage data on which to base the recommendation. The amount is in past hours of data counting from when the platform starts generating the recommendation.

For example, if you set this to 10, the platform always generates the recommendation based on the last 10 hours of usage data collected from the site.

The minimum value is 1. The maximum value is 1440 (60 days).

The default value is 1.

Maximum number of recommended items to return.

The minimum value is 1. The maximum value is 120.

The default value is 20.

Names for the Recommendations API request parameters for filtering the recommendation results. The parameters you define here determine the parameters that you can use in a request to filter which recommended items to return.

For example, if you're creating a product recommendation and want to filter the results by product category and price, define the names for two parameters: one for category and the other for price, such as category and price.

Defining the parameters

You can filter the results by any data field. You can also filter the results by segment if the recommendation type is most_converted or most_viewed. How exactly you want to filter the results, and therefore what parameters to define for the request, is up to you.

If the recommendation type is bundle_converted, bundle_viewed, or bundle_viewed_converted, define only a single parameter: the target field against which the recommendation is generated. For example, if you want to recommend products purchased together with a product the visitor just added to their shopping cart, define a parameter for product ID, since the recommendation is based on a specific product. Do not define any other parameters.

If the recommendation type is most_converted or most_viewed, and if you want to filter the results by segment, define a parameter for segment ID as the last string in the array.

You can freely name the parameters.

You must define at least one parameter.

For information about using the parameters in a request, see Recommendations API reference (configurations).

Filter recommended items by category:

"params": [
  "category"
]

Filter recommended items by category and brand:

"params": [
  "category",
  "brand"
]

Filter recommended items by category, price, and visitor segment:

"params": [
  "category",
  "price",
  "segment"
]

Logic for mapping the IDs of the recommended items to source data in the Frosmo back end. This determines what data the recommendation actually returns for each item.

The possible values are:

• product: Map each item ID to a product ID. Return the full product data for each ID.
• Empty string: Do not map the item IDs to anything. Return the raw recommendation data (ID and recommendation weight) for each item.

If you're creating a product recommendation and want to return the full product data in the recommendation results, set this property to product.

The default value is product.

Map each item ID to a product ID:

"map_ids": "product"

Do not map the item IDs:

"map_ids": ""

Configuration options specific to recommendation type.

If you have no options to define, set this property to an empty object ({}).

The default value is {}.

For more information, see Options object.

Advanced product data filters for refining the set of recommended products to return.

While params define the fields and segments that you can specify in a Recommendations API request to filter the results, filters define advanced result filtering that the platform applies automatically to all requests.

If you define multiple filters, the platform applies them all, that is, the platform treats the filters as combined with logical AND operators. The platform only returns items for whom all the filters evaluate to true.

The platform automatically applies filters on top of the filtering performed with params. If a request does not perform any filtering with params, the platform nonetheless applies the filters, if defined.

The default value is null.

For more information, see Filter object.

Exclude books:

"filters": [{
    "name": "Exclude books",
    "rules": [{
        "attribute": "type",
        "operator": "!=",
        "value": "Books"
    }]
}]

Only return books whose title ends with "for dummies" and that cost less than 30 (in the site currency):

"filters": [{
    "name": "Include 'For Dummies' books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    },{
        "attribute": "name",
        "operator": "endsWith",
        "value": "for dummies"
    }]
},{
    "name": "Include items that cost < 30",
    "rules": [{
        "attribute": "price",
        "operator": "<",
        "value": "30"
    }]
}]

For more examples, see Filter examples.

Error trace of what happened when the recommendation data generation failed.

If the data generation was successful, the value is an empty string.

Date and time when the recommendation configuration was created.

For more information about the date and time format, see Graniitti API: Resources.

Date and time when the recommendation configuration was last updated.

For more information about the date and time format, see Graniitti API: Resources.

Date and time when the recommendation data was last generated.

For more information about the date and time format, see Graniitti API: Resources.

Version of the data schema used by the platform to generate and structure the recommendation data.

The current and only supported version is 2.

Delimiter string by which to split the product category value. If the string is empty, the product category value is not split.

If you define a delimiter, you must include type in product_attrs.

The default value is an empty string ("").

Minimum data point weight for including the data point (item) in the recommendation results.

For bundle product recommendations, a data point is a single recommended product, and the data point weight is the total number of times the product was purchased or viewed together with other products.

The default value is 0, meaning all data points are returned.

Names of the product attributes by which to filter the recommendation results when using request parameters.

Define the names of the product attributes that correspond to the request parameters defined in the params array. You must define a matching product attribute name for every parameter (except for the final segment parameter, if defined) and in the order in which the parameters are defined in params. The names must match actual product attributes in the product data stored for your site.

To find out the available product attributes, use the Product API.

The product_attrs array tells the platform how to map the parameters in the Recommendations API request to product attributes in the product data stored for the site.

For example, if you've defined a request parameter for product category, define type as the product attribute name to which the parameter maps, since type is the product attribute for product category or type.

You must define at least one product attribute name (corresponding to the one minimum request parameter in params).

One request parameter defined. Map the parameter to product category:

"product_attrs": [
  "type"
]

Two request parameters defined. Map the first parameter to product category and the second parameter to product brand:

"product_attrs": [
  "type",
  "brand"
]

No request parameters defined. Map nothing.

"product_attrs": []

IDs of the segments by which you want to allow the recommendation results to be filtered. You can use the IDs in Recommendations API requests (as the value of the segment parameter) to retrieve the recommendations only for a given segment.

If you define one or more segment IDs, the params property must include a single parameter for segment ID as its last item.

If you do not define the ID of a given segment, you cannot filter the results by that segment.

For example, if you define segment as the last item in the params property, and you define the segment IDs 123 and 456 in this property, you can use either "segment": "123" or "segment": "456" as a parameter in a Recommendations API request to filter the returned items by the corresponding segment. You could not use the parameter "segment": "789", for example, since you did not define the segment ID 789.

The default value is [].

Allow filtering by two segments:

"segments": [
  123,
  456
]

Do not allow filtering by any segment:

"segments": []

One or more rules that together define the filtering logic for the filter.

If you define multiple rules, the platform applies them all, that is, the platform treats the rules as combined with logical AND operators. The platform only returns products for whom all the rules evaluate to true.

For more information, see Filter rule object.

Relational operator used to compare the value of the product attribute defined in attribute to the target value defined in value. The comparison is case-insensitive.

By default, the platform treats the product attribute and the target value as strings.

For more information about the supported operators, see Filter rule operators.

Target value against which the value of the product attribute defined in attribute is compared.

The value can be either a regular string or, if the operator is in, notIn, or startsWithAny, a JSON-stringified array of strings.

For regular expressions (regex and notRegex operators), use the RE2 syntax.

If the operator is exists or notExists, do not define a target value.

Compare against a regular string:

"value": "Books"

Compare against a JSON-stringified array of strings:

"value": "[\"Books\",\"Magazines\"]"

The rule evaluates to true if the attribute value equals the target value.

Rule: <type> = "Fashion/Shoes"

type: "Fashion/Shoes" -> TRUE
type: "Fashion/Suits" -> FALSE

The platform converts the attribute value to a string for the comparison.

Boolean

Number

String

The rule evaluates to true if the attribute value does not equal the target value.

Rule: <type> != "Fashion/Shoes"

type: "Fashion/Shoes" -> FALSE
type: "Fashion/Suits" -> TRUE

The platform converts the attribute value to a string for the comparison.

Boolean

Number

String

The rule evaluates to true if the attribute value is greater than the target value.

Rule: <price> > than 50

price: 40 -> FALSE
price: 50 -> FALSE
price: 60 -> TRUE

If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.

Number

String

The rule evaluates to true if the attribute value is less than the target value.

Rule: <price> < 50

price: 40 -> TRUE
price: 50 -> FALSE
price: 60 -> FALSE

If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.

Number

String

The rule evaluates to true if the attribute value is greater than or equal to the target value.

Rule: <price> >= 50

price: 40 -> FALSE
price: 50 -> TRUE
price: 60 -> TRUE

If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.

Number

String

The rule evaluates to true if the attribute value is less than or equal to the target value.

Rule: <price> <= 50

price: 40 -> TRUE
price: 50 -> TRUE
price: 60 -> FALSE

If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.

Number

String

The rule evaluates to true if the attribute value contains or equals the target value.

Rule: <type> contains "shoes"

type: "Fashion/Shoes" -> TRUE
type: "Fashion/Suits" -> FALSE

The rule evaluates to true if the attribute value does not contain or equal the target value.

Rule: <type> notContains "shoes"

type: "Fashion/Shoes" -> FALSE
type: "Fashion/Suits" -> TRUE

The rule evaluates to true if the attribute value begins with or equals the target value.

Rule: <type> startsWith "Fashion"

type: "Fashion/Shoes" -> TRUE
type: "Food/Seafood" -> FALSE

The rule evaluates to true if the attribute value begins with or equals any one of the target values.

The target value must be a JSON-stringified array of strings.

Rule: <type> startsWithAny "[\"Fashion\",\"Food\",\"Toys\"]"

type: "Fashion/Shoes" -> TRUE
type: "Food/Seafood" -> TRUE
type: "Home/Bedroom" -> FALSE

The rule evaluates to true if the attribute value ends with or equals the target value.

Rule: <type> endsWith "Shoes"

type: "Fashion/Shoes" -> TRUE
type: "Food/Seafood" -> FALSE

The rule evaluates to true if the attribute value equals any one of the target values.

The target value must be a JSON-stringified array of strings.

Rule: <brand> in "[\"Cakita\",\"Kosch\",\"Wakita\"]"

brand: "Cakita" -> TRUE
brand: "Dawelt" -> FALSE
brand: "Wakita" -> TRUE

The platform converts the attribute value to a string for the comparison.

Boolean

Number

String

The rule evaluates to true if the attribute value equals none of the target values.

The target value must be a JSON-stringified array of strings.

Rule: <brand> notIn "[\"Cakita\",\"Kosch\",\"Wakita\"]"

brand: "Cakita" -> FALSE
brand: "Dawelt" -> TRUE
brand: "Wakita" -> FALSE

The platform converts the attribute value to a string for the comparison.

Boolean

Number

String

The rule evaluates to true if any one of the attribute values equals the target value.

Rule: <features> arrayIncludes "respins"

features: ["respins", "scatters", "wilds"] -> TRUE
features: ["paylines", "scatters", "wilds"] -> FALSE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of numbers

Array of strings

The rule evaluates to true if none of the attribute values equal the target value.

Rule: <features> arrayNotIncludes "respins"

features: ["respins", "scatters", "wilds"] -> FALSE
features: ["paylines", "scatters", "wilds"] -> TRUE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of numbers

Array of strings

The rule evaluates to true if at least one of the attribute values equals at least one of the target values.

Rule: <features> arrayIncludesAny ["respins", "wilds"]

features: ["respins", "scatters", "wilds"] -> TRUE
features: ["free spins", "paylines", "scatters"] -> FALSE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of Booleans

Array of numbers

Array of strings

Array of Booleans

Array of numbers

Array of strings

The rule evaluates to true if none of the attribute values equals none of the target values.

Rule: <features> arrayNotIncludesAny ["respins", "wilds"]

features: ["respins", "scatters", "wilds"] -> FALSE
features: ["free spins", "paylines", "scatters"] -> TRUE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of Booleans

Array of numbers

Array of strings

Array of Booleans

Array of numbers

Array of strings

The rule evaluates to true if any one of the attribute values contains or equals the target value.

Rule: <tags> anyElementContains "sale"

tags: ["shirts", "short-sleeve", "top-rated"] -> FALSE
tags: ["shirts", "long-sleeve", "summer sale"] -> TRUE
tags: ["skirts", "sale 50%", "top-reviewed"] -> TRUE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of Booleans

Array of numbers

Array of strings

The rule evaluates to true if any one of the attribute values begins with or equals the target value.

Rule: <tags> anyElementStartsWith "top"

tags: ["shirts", "short-sleeve", "top-rated"] -> TRUE
tags: ["shirts", "long-sleeve", "summer sale"] -> FALSE
tags: ["skirts", "sale 50%", "top-reviewed"] -> TRUE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of Booleans

Array of numbers

Array of strings

The rule evaluates to true if any one of the attribute values ends with or equals the target value.

Rule: <tags> anyElementEndsWith "sleeve"

tags: ["shirts", "short-sleeve", "top-rated"] -> TRUE
tags: ["shirts", "long-sleeve", "summer sale"] -> TRUE
tags: ["skirts", "sale 50%", "top-reviewed"] -> FALSE

The platform converts the attribute values to strings for the comparison.

The platform expects the attribute values to be of the same type.

Array of Booleans

Array of numbers

Array of strings

The rule evaluates to true if the attribute value is inside the specified duration counting backwards from the current date and time of your Frosmo Platform instance.

The attribute must be one of the following datetime attributes:

• created_at
• feed_updated_at
• updated_at
• Any string attribute that represents an ISO 8601 datetime value

The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are h (hours) and d (days). For example: 24h or 7d.

Rule: <created_at> during "10d"

Current time: 2022-09-10 12:00:00 UTC+2

created_at: "2022-09-01T15:00:00+02:00" -> TRUE
created_at: "2022-08-28T15:00:00+02:00" -> FALSE

The platform subtracts the attribute value from the current date and time, and compares the result to the target value (duration). If the result is less than or equal to the target value, the operation evaluates to true.

If the attribute value is a future datetime, the operation always evaluates to true. You therefore cannot filter out items whose datetime is in the future.

Example: The current date and time is 2022-09-10 12:00:00, the attribute value is 2022-09-01 15:00:00, and the target value is 10d. Subtracting the attribute value from the current date and time yields 8d 21h. The result is less than the target value, the operation evaluates to true, and the item is therefore included in the recommendation results.

The rule evaluates to true if the attribute value is not inside the specified duration counting backwards from the current date and time of your Frosmo Platform instance.

The attribute must be one of the following datetime attributes:

• created_at
• feed_updated_at
• updated_at
• Any string attribute that represents an ISO 8601 datetime value

The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are h (hours) and d (days). For example: 24h or 7d.

Rule: <created_at> notDuring "10d"

Current time: 2022-09-10 12:00:00 UTC+2

created_at: "2022-09-01T15:00:00+02:00" -> FALSE
created_at: "2022-08-28T15:00:00+02:00" -> TRUE

The platform subtracts the attribute value from the current date and time, and compares the result to the target value (duration). If the result is greater than the target value, the operation evaluates to true.

Example: The current date and time is 2022-09-10 12:00:00, the attribute value is 2022-08-28 15:00:00, and the target value is 10d. Subtracting the attribute value from the current date and time yields 12d 21h. The result is greater than the target value, the operation evaluates to true, and the item is therefore included in the recommendation results.

The rule evaluates to true if the attribute exists.

The attribute exists if the platform has tracked at least one value for the attribute.

Do not define a target value.

Array of Booleans

Array of numbers

Array of strings

Boolean

Number

String

The rule evaluates to true if the attribute does not exist.

The attribute does not exist if the platform has not tracked any values for the attribute.

Do not define a target value.

Array of Booleans

Array of numbers

Array of strings

Boolean

Number

String

The rule evaluates to true if the attribute value matches the defined regular expression.

Rule: <name> regex "^[Aa]\w+s$"

name: "Aliens" -> TRUE
name: "ALIENS" -> FALSE

Define the regular expression using the RE2 syntax.

The rule evaluates to true if the attribute value does not match the defined regular expression.

Rule: <name> notRegex "^[Aa]\w+s$"

name: "Aliens" -> FALSE
name: "ALIENS" -> TRUE

Define the regular expression using the RE2 syntax.

Product data

Transaction

Product

Transaction