recsForPlacements

Already added registry items. A single (or list of) product ID(s). If there is more than one product in the registry, separate the IDs using the pipe '|' character.

Example: ​aari=33306|909119|305466

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

Example: apiClientKey=b0126f995ac848159d

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

Example: apiKey=4faeaf752ee40a0f

Add to Cart ID. This should be a single product ID.

Example: atcid=uv2345

This parameter limits the product attribute information included in the result to the specified list of attributes.

attributeList takes comma separated list of attribute names that should be shown in the response.

If the parameter is empty or wild card character '*', it will display all the product attributes in the response.

Example:

If attributeList = gender,color. Then it will return only gender and color attributes in the product attribute information.

attributeList=*   Returns all product attributes.

attributeList= (Empty) Returns all product attributes.

Note: If returnMinimalRecItemData option is set to true in the request which naturally returns a minimum set of information, and attributeList option is also specified, the response also includes the attributes specified in the parameter.

A list of product IDs that should not be recommended in this response. Use the pipe "|" character to separate product IDs.

Example: bi=93874|04495|043945

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

Example: categoryData=false

Note: excludeAncestor=false can be used to include the ancestor data.

The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to Algonomy for the category.

Example: categoryId=902312

This attribute returns the following category details for products in strategy:

• Category ID

• Category Name

• Category Link URL

• Category Image URL

When categoryData is set to True for a strategy, each product returned for that strategy will include categoryRec in the response.

Example: categoryRec=true&categoryData=true

For more details on categoryRec, see Adding 'categoryRec' attribute in response

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

The total number of products to return in the response. This value overrides the return count set in the placement or in the Search and Browse configuration. For example, if you want to return products 30 through 60, set the value to 30. The maximum value is 1000.

Example: count=30

Note: This is for Search and Browse only. When using pagination this parameter together with st is required.

Click-through parameter. Used to add parameters to the click-through URL. See Click-through Parameters for more information.

Example: ctp=|0:origin=CJ|1:&campaign=rr

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, www.buystuff.com vs. m.buystuff.com). This parameter is typically used during development to keep users within the same environment when clicking on a recommendation. 

Example: cts=http://test.buystuff.com

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 to 95.50)

True/False. When set to false, the response will include the ancestor data in the ancestorCategories array in the "categories" object.

Note: This parameter is meant to be used with categoryData parameter.

Example: excludeAncestor=false

Example JSON Response:

"categories": [
  {
    "hasChildren": false,
    "name": "Solder",
    "childCategories": [],
    "ancestorCategories": [
      {
        "hasChildren": true,
        "name": "Metals",
        "childCategories": [],
        "ancestorCategories": [],
        "id": "4",
        "isActive": false
      }
    ],
    "id": "1572",
    "isActive": false
  }
],

True/false. If true, it omits the HTML returned in the Algonomy 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

True/false. If true, it removes item attributes from the recommended products data. The default is false.

Example: excludeItemAttributes=true

True/false. If true, it completely removes the recommended items structure. This is useful when HTML is sufficient for the response. The default is false.

Example: excludeRecItems=true

Force Display Mode. True/false. If true, the parameter will force display. For example, in listen mode, it will return products bypass logging.

Valid Values:

For true: "t", "on", "yes", "true", "1", "y" 

For false: "f", "off", "no", "false", "0", "n"

Filter by brand name. The default excludes products of the specified brand from being recommended. See includeBrandFilteredProducts to change the default function. Filter multiple brand names by using the pipe "|" character between names.

Example: filbr=Microsoft|Logitech|Apple

Specify the category to filter.

filcat=<categoryId>

To filter based on a specified category, the following should be specified: "filcat=<categoryId>&filcatinc=true>"

Multiple category ids can be passed with pipe de-limited string. Each category in a string is OR'd

Filter along category (requires specification of category with 'filcat')

filcatinc=true: filters results to only show products from the specified category

filcatinc=false: filters out results from the specified category

Filter types and values selected by the shopper. Place quotation marks around all attributes, separate the types by using the pipe "|" character, and separate the values by using a semicolon. You must include quotation marks around all attributes.

Example: filterAtr=brand:"adidas"|size:"M";"L"

Note: This is for Search and Browse only, and it needs configuration by Algonomy first.

Flash version of the browser. It's only used if content displayed is flash.

Example: flv=20.0.0.306

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

Example: fpb=Microsoft

True/false. Changes the function of filbr from exclude to include. If not specified, the default is false, which will exclude the specified brand. If true, the brand filter excludes all products except the specified brand.

Example: includeBrandFilteredProducts=true

True/false. The default is false. If true, it includes details about any multivariate test (MVT) that is running.

Example: includeMVTData=true

Example JSON Response:

"mvt":
[
{ "testId":12953, "control":false, "treatmentId":15707, "treatmentName":"T2 - recs OFF” }
], 

True/false. The default is false. If true, it includes details about any multivariate test (MVT) that is running. The “eligible” string parameter will define that if the user is eligible for an MVT test or not.

Example: includeMVTDetailedData=true

Example JSON Response:

"mvtDetailed":
[
{ "eligible":true, "testId":12953, "control":false, "treatmentId":15707, "treatmentName":"T2 - recs OFF” }
]

When set to true, for Placement Type of Tests, the response will include a new section "mvtTreatments” providing MVT details that a placement is associated with.

Example JSON Response:

"placements":[
{
"mvtTreatments": [
{
"testType": "Placement”,
"testId": 55564,
"control": true,
"treatmentId": 60129,
"treatmentName": "swap_each_other"
}
]

Note: Only the treatments a placement is participating will be provided as part of the response. If the Placement test includes multiple placements, then all the placements will include the “mvtTreatment” as part of the response. If multiple Placement tests are happening for the same placement, then multiple treatments will be part of the response.

True/False, the default value is false. If true, any available sku data provided in the SKU Feed will be provided for the returned products. Example: includeSkuData=true

Example JSON Response:

"skuData": [{
  "color": "White",
  "size": "12",
  "image_url": "http://demandware.edgesuite.net/9400.jpg",
  "sku_id": "9400"
}, {
  "color": "White",
  "size": "13",
  "image_url": "http://demandware.edgesuite.net/9401.jpg",
  "sku_id": "9401"
}]

True/false. Changes the function of minPriceFilter and maxPriceFilter from exclude to include. If not specified, the default is false, and it excludes product prices that match the specified range. If true, the filter excludes all products outside of the price range.

Example: includePriceFilteredProducts=true

True/false. Default is false. If true, each placement in the response will include the strategy name.

Example: includeStrategyData=true

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

Example: ipor=255.255.255.255

Name of the JavaScript function that JSON data is passed to. Must be specified if jsonp is set to true.

Example: jcb=processData

Boolean flag. The only valid value is true. If set to true, the jcb parameter must also be provided.

Example: jsonp=true

The maximum value of the price range filter. This filter matches the sale price of a product, or the list price if no sale price is provided. The value is in cents.

Note: This parameter will not work correctly unless includePriceFilteredProducts is also used. 

Example: maxPriceFilter=10099 (this means $100.99) 

The minimum value of the price range filter. This filter matches the sale price of a product, or the list price if no sale price is provided. The value is in cents.

Note: This parameter will not work correctly unless includePriceFilteredProducts is also used. 

Example: minPriceFilter=579 (this means $5.79) 

Order ID. Part of the order definition.

Example: o=902312

The total number of pages to return in the response. The total number of products returned are (count * pageCount), up to the total number of products in the category. Default pageCount is 1. This feature allows paginated Discover responses to be incorporated into faceted search and navigation systems. For large pageCount values, we advise returning small amounts of data per product, such as with these additional parameters : "&excludeHtml=true&excludeItemAttributes=true&returnMinimalRecItemData=true"

Example: pageCount=50

Note: This is for Discover only.

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

Product prices. A list defining the prices of purchased products. The index of product prices in the list corresponds to the products passed in productId. This is part of the order definition. Use either pp or ppc to define the price of items purchased. If you use pp, the site’s currency multiplier is applied. The values are separated by the pipe "|" character.

Example: pp=29.99|32.97

Product prices in cents. A list defining the prices of purchased products. The index of product prices in the list corresponds to the products passed in productId. This is part of the order definition. Use either pp or ppc to define the price of items purchased. If you use ppc, the site’s currency multiplier is not applied.

The passed value is accepted as-is, and is converted from a string to an integer. Be certain that the string you pass contains only numerals (no currency symbols or separators). The values are separated by the pipe "|" character.

Example: ppc=2999|3297 (these values are $29.99 and $32.97)

Filter based on the price ranges that products should belong to. This is not applicable for clients with localized product prices. The values are in cents, and the value ranges are separated by the pipe "|" character.

Example: priceRanges=0;100|500;1000

Note: This is for Search and Browse only. 

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

Note: For the add_to_cart_page request, the product ID is passed as the Add to Cart ID through the'atcid' parameter. Hence this producId field is not required.

Note: SKU IDs can be passed to API calls as well. When specifying a PRODUCT ID, the SKU ID should be appended with a tilde ('~') separator. Example: ...&productId=[product_id]~[sku_id]

Item quantities. A list defining the quantities of products purchased. The index of quantities in the list corresponds to the index of the products passed in productId. This is part of the order definition. Multiple entries are separated by the pipe "|" character.

Example: q=2|1

Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.

This will limit the recommendedProducts json to 4 attributes: id, productURL, clickURL, clickTrackingURL

Used to identify a particular registry.

Example: rg=Registry123454321

Registry type ID. Contact Algonomy for a list of registry type IDs for your site.

Example: ​rgt=wedding

Region ID. Must be consistent with the ID used in the Product Region Feed.

Example: rid=Switzerland-France

The search term typed in by the shopper. You can also use the productId parameter to provide product IDs of the products in the search results.

Example: searchTerm=adriana lima

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

The starting number for the products that you want to return. For example, if you want to return products 30 through 60, set the value to 30.

Note: This is for Search and Browse only. When using pagination this parameter together with count is required.

Example: st=30

A prioritized list of strategy sets that you want returned based on the campaign use case. Please see additional details under Strategy Families listing below. If this is not provided, our recommendation engine will run King of the Hill (KOTH) to provide best recommendations given the information provided.

Example: strategySet=SiteWideBestSellers or strategySet=ProductBoughtBought|ProductViewedViewed

Timestamp. It's used for browser cache busting, and is highly recommended. If excluded, you may see cached responses.

Example: ts=1376676943

Use Dummy Data. True/false. If true, it returns random products for testing.

Example: udd=t

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

Usage is same as userAttribute, except that the attributes sent along with userAttributeReplace will replace all previously sent values for that attribute.

Example: userAttributeReplace=eye_color:black

In the above example all previous values of eye_color will be removed and replaced with black.

If the same attribute is sent along in a single request in userAttribute as well as userAttributeReplace, then the value sent in userAttributeReplace will take precedence.

This attribute also supports Delete update against attribute values. Example: userAttribute=eye_color:|hair_color:

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 Algonomy in other applications.

Example: userId=0982347

Refinements are used to assure recommended products have a specific attribute value or values. An individual refinement is specified as a colon separated name/value pair.

Example: rfm=name:value

To specify a refinement as the existence of the attribute, you can simply omit the value

Example: rfm=name

To specify multiple refinements, specify them as a delimited list using the pipe character ('|') as the delimiter.

Example: rfm=attributeName|attributeName1:value1|attributeName2:value2

For more information, refer to the Refinements section.

Refines recommendations based on multiple values using 'and' and 'or' logic operators, with the pipe character ('|') as the delimiter to separate the values.

Note: Note: rfm_cond will only be applied if rfm is being used. If the 'rfm_cond' parameter is not present in the request, the default behavior (i.e 'and' logic) will be considered.

Example: rfm=attributeName:value1|attributeName2:value2&rfb=false&rfm_cond=or

Refinement Fall-Back. Controls the cul-de-sac fallback behavior of refinements. 

Example: rfb=false

Default value is true, meaning that refinement values that would reduce recommendations below the placement's minimum threshold will be discarded. 

For more information, refer to the Refinements section.