Skip to main content



  • Returns content for the given user and placement.


Note:  All paramets are case sensitive.

Important: Only call parameters that you need. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance may update and enhance these APIs at any time. If you are building a mobile app, please use our mobile SDKs.

Name Required or Optional Description



A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by RichRelevance.

Example: apiClientKey=b0126f995ac848159d



A unique key that identifies the site. Each RichRelevance client has a unique API key to separate data and traffic from other clients. This is provided by RichRelevance.

Example: apiKey=4faeaf752ee40a0f



Retrieves custom attributes provided in the catalog feed. Use this parameter multiple times to request more than one attribute by separating each attribute with the ampersand "&" character. Use the asterisk "*" character as the parameter value to request all attributes.

Example: &attribute=COLOR&attribute=SIZE



Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response.

Example: callback=products_returned



Omits category data (categoryIds and categories) when set to false. The default is true.

Example: categoryData=false



Supplies category hint IDs. Category hints can be added to any page type. Each category hint qualifies the page for merchandising rules that are associated to the category. Merchants can add multiple category hints to a single page. The values are separated by the pipe "|" character. 

Example: chi=1913000|1903094



External category IDs used to pass category context information. For the category_page, the expected value is a single external category ID. For other page types, this can be a list of category IDs. The category IDs must be separated by the pipe "|" character. 

Example: cis=2123048|1903094



Category name.

Example: cn=Baby


Required for Promo and Email

Email campaign ID. This can be alphanumeric.

Example: cpi=summerCoolOff2016



Click-through server. Changes a portion of the click-through URL when a shopper clicks on a recommendation. It specifies the destination server of the click (for example, vs. This parameter is typically used during development to keep users within the same environment when clicking on a recommendation. 

Example: cts=

Note: if the cts parameter is provided in the API request, it overrides the click-through server site configuration setting, and/or cts in the product URL delivered in the feed.



Cart value. Used for targeted campaigns involving cart value. It's expressed in cents; for example, $10 is represented as 1000.

Example: cv=9550 (this would equal $95.50)



True/false. If true, it omits the HTML returned in the RichRelevance server response. If false, the response includes the HTML for the placement which is set in the layout of the html field. The default is false. 

Example: excludeHtml=true



The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers.

Example: fpb=Microsoft



Shopper IP address. Only use if the API request is not coming from the shopper’s device (for example, server-side integration).

Example: ipor=



List of placement identifiers. Each identifier consists of a page type and a placement name. The identifiers are separated by the pipe "|" character.

  • You'll receive one set of recommendations per placement.
  • All placements must be for the same page type.
  • The first placement is assumed to be the "best" placement, and will receive the best recommendation strategy.
  • When multiple placements are requested, each will receive a unique strategy and unique products.

Example: placements=item_page.horizontal|item_page.vertical



Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended.

Example: pref=



Products the shopper has purchased in the current session. This can be a single product ID or list of product IDs. Products listed here will be considered along with historical data from the RichRelevance system. Use the pipe "|" character to separate the product IDs.

Example: recentlyPurchased=uv2345|xt1234



List product IDs of the product detail pages viewed by the shopper in the current session. Include time stamps in milliseconds using UTC time zone for each view. The timestamp field must be provided. Use the pipe "|" character to separate multiple product IDs and time stamps. If there are multiple views for a product ID, the time stamps can be concatenated using a semicolon.

Example: recentlyViewed=pid1:1409871261000;1409871561000|pid2:1409761261000



Upper limit on the number of recommendations returned by each strategy. The default is 5, and the maximum is 20.

Example: recProductsCount=8



Region ID. Must be consistent with the ID used in the product region feed.

Example: rid=Switzerland-France



Identifies a single visit by a shopper.  Sessions are used by behavioral models (to scope user behaviour in a shopping session) and reporting metrics.

Example: sessionId=93484



Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "|" character to separate segments. You must pass both the segment ID and a segment name for each segment.

Example: sgs=101:NewUser|202:Male



Use recently viewed product information from the RichRelevance cookie as a basis for recommendations along with manually-given recommendations. Default is yes.

Example: useCookie=yes



Custom keys and values that describe the current shopper. Separate information using a semicolon and the pipe "|" character.

Example: userAttribute=eye_color:blue;green|hair_color:brown



User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to RichRelevance in other applications.

Example: userid=0982347

If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers. 

Example Request

Example Response

                "html":"<div><a href=""><img src="" alt="Cat"></a><img src=""></div>"
                            "campaign":"AZ multi layouts test campaign 1",
status: "OK",
message: "",


Field Description
placements List of placements with promotions based on the request. This is an array of JSON objects, each describing a single placement..
creatives A list of the creatives to be displayed. In most cases, this will only be one.
html Fully formed HTML for the placement based on the layout and selected campaign. It is included in the response by default. Turn off by using the excludeHtml request parameter.
status A list of the creatives to be displayed. In most cases, this will only be one.
errormessage Either ‘ok’ or ‘error’.
request The parameters from the request that RichRelevance used in processing the request. Typically used for testing purposes.
trackingUrl Email open event tracking URL. This should only be used when Promo is rendered within an email.

Example: trackingUrl;s=1&amp;vg=80007fe3-0b35-4b62-5ad3-67513881024f&amp;u=1&amp;cpi=emailCampaign1&amp;pgt=30&amp;pa=rr_promo2&amp;pt=email_page.rr_promo2&amp;cis=292023&amp;cn=the+sale&amp;pcam=580224&amp;pcre=8753