Skip to main content

Find: Track Add to Cart API


POST<API_KEY>? <Parameters> 

This API records an add to cart event for a product featured in the search results and is used for Add to Cart conversion reporting.

This API should only be used when the item that is being added to the cart is the result of a search, usually when an add to cart button on the search result page is clicked to add the item to the cart. If no add to cart button is present on the search result page, retailers can opt to locally store the "addtoCartParams" value returned with the response so that when the shopper clicks on a product from the search result page and then adds to cart from the product description page, they can then send the "addtoCartParams" to the API to track the conversion.

The Find Response returns the addtoCartParams which contains part of the parameters that need to be sent in the Add to Cart API:

  • page
  • query
  • lang
  • searchConfigId

The other parameters like productId, userId, sessionId, rcs, etc. need to be added as you normally would

If the site also has Recommend and/or Discover implemented, for an Add to Cart click on the search result page, you will have the following tracking:

  • Product click thru link provided by Find response for each product
  • Add to cart API with the addtocart params + productId + additional parameters
  • Add to cart recsForPlacements tracking - ONLY if Recommend and/or Discover is implemented.

Please refer to Add to Cart Page for the add to cart integration. Please refer to the Integration with Find section on that page.


Name Data Type Required or Optional Description


String Required

The search term that was used.

Example: query=shoes

lang String Required The language of the search.  Examples: "en", "fr", "jp".
productId String Required The product id of the item being added to the cart.
page Number Required Page number where the product was displayed on the search result view.
searchConfigId String Required Config id returned by the search api
userId String Optional

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.

sessionId String Required

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

channelId String Optional A channel is a description of the caller of this API.  It's mostly used to describe whether this API is being used in an Android app or a Call center app.
region String Optional Region Identifier
rcs String Optional

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.

Example Request<APIKEY>?query=t&lang=en&user=u1234&session=s1234&channel=ch1234&region=reg1234&page=0&productId=10308694&searchConfigId=1234


Response code Description

202 accepted

Returned when request is processed successfully
500 error Returned when find is not correctly setup for a site or the site api key is incorrect.
  • Was this article helpful?