Retrieve by page

Beta: This endpoint is in beta and may change. It is currently available to a small group of users. To request access, contact your Customer Success Manager.

Retrieve recommendation results for every pod configured on a page in one request. Results are deduplicated across the page's pods server-side, so an item (or, if the page deduplicates by variation, an item variation) is returned by at most one pod unless it is slotted.

Shared parameters apply to every pod on the page. Use pod_overrides to give a pod its own num_results, filters, filter_match_types, pre_filter_expression, fmt_options or variations_map; every other parameter is page-wide. Prefer GET: every parameter, including pod_overrides (in bracket notation), can be sent in the query string. POST is also accepted, with pod_overrides as a JSON object in the body. The body accepts only pod_overrides; all other parameters stay in the query string.

Each element of response.pods carries the pod's effective request, its response and its result_id. A pod's response is the response of the single-pod endpoint, except experiments, which the page carries once, so existing rendering code can be reused.

Send the pod's own result_id (response.pods[].result_id) with that pod's recommendation_result_view and recommendation_result_click events. The top-level result_id identifies the page request and is not a beacon id.

Path Params
string
required
Query Params
string
required
length between 1 and 100

The key of the index to use.

string
length between 1 and 100

The section of the index to use. Defaults to the key's default search section, usually Products.

string | array

The ID of the item to recommend additional items for. This parameter is required for the following recommendation strategies

  • alternative_items
  • complementary_items
  • bundles
  • visually_similar_items
pod_overrides
object

A map of pod_id to per-pod parameter overrides. An override replaces the corresponding shared parameter for that pod only; it is not merged with it. A filters override replaces all of the shared filters, so repeat any shared filter the pod still needs. Overridable parameters: filter_match_types, filters, fmt_options, num_results, pre_filter_expression, variations_map. Every other parameter is page-wide, and supplying one in an override returns 400. In the query string, use bracket notation, such as pod_overrides[similar_items][num_results]=12. With POST, you can instead send an object in the request body. Query and body overrides merge per parameter, and the body wins when both set the same parameter for the same pod.

string | array

The ID of the item variation to recommend additional items for. This parameter can be used with exactly one item_id specified in the request and is not required.

string
length between 0 and 100

The term to recommend items for. This parameter is required for the following recommendation strategies

  • query_recommendations
filters
object

Any number of filtering criteria (accessible to end users) used to narrow the result set, such as color=blue or group_id=sandals or price=100-200. Facets and Item Groups and Collections can be used as filters. If filter_value has the form <min>-<max>, it is interpreted as a range. Filters with the same key are ORed together and filters with different keys are ANDed together by default. Only results that match the filters are returned.

This parameter is required for the following recommendation strategies

  • filtered_items
filter_match_types
object

An object specifying whether results must match all, any or none of a given filter when multiple options of the same facet (e.g: color: yellow & blue) are selected.

object | Encoded JSON string

A JSON Object containing any number of filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Only results that match the filters are returned.

integer
0 to 100
Defaults to 10

The maximum number of recommended items to retrieve

json

A JSON string containing instructions on how to map item variation data in the response (typically used for swatches). More details, including the exact schema for this value can be found here

fmt_options
object

An object containing options to format the results returned

string

The url or app location where the request originated.

string
length between 1 and 100

The ID of the client and version that the request is coming from, such as cio-js-2.90.

us
array of strings

User segment is a client context value (such as platform, location, etc.) that is used to evaluate recommendation rules that target user segments. You can supply multiple segments by passing multiple us arguments.

us
string

A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.

At least one of the parameters i or ui is required for the following recommendation strategies

  • recently_viewed_items
  • user_featured_items
  • abandoned_in_cart
  • buy_it_again
integer

An integer representing the users session number (starting with 1), incremented after a 30 minute period of inactivity.

string

A globally unique identifier for the user browser (or mobile application instance) making the request.

At least one of the parameters i or ui is required for the following recommendation strategies

  • recently_viewed_items
  • user_featured_items
  • abandoned_in_cart
  • buy_it_again
string
length between 0 and 100
deprecated

DEPRECATED. Please, use term instead

Headers
string

Backend only. The token that Constructor gives you for a backend integration. Send it on every request from your servers. Never send it from a browser or an app, because anyone can read it there. See Required parameters.

string

The User-Agent of the end user's device. A browser sends it for you. In a backend integration, forward the value from the end user's browser. In a native app, use the format on Required parameters.

string

Backend only. The IPv4 address of the end user's device. Send one address, not a comma-separated chain. IPv6 addresses are not supported. Constructor reads this header only when the request also has a valid x-cnstrc-token. See Required parameters.

Responses

400

Validation Error

404

Not Found

Language
LoadingLoading…
Response
Choose an example:
application/json