Constructor is unique in that it is designed to optimize for business KPIs. Most commonly this means optimizing revenue-per-visitor and/or purchase conversion rate. .

In addition to purchase conversion events, Constructor allows customers to communicate a wide array of additional success events that may happen independently from purchase (for instance reading a recipe) or may happen as an event preceding purchase (adding to cart or messaging a seller in a marketplace). These success indicators can be used to train Constructor's model and in future will be shown in the dashboard to differentiate from likes, messages and add to carts in the dashboard interface, as an example.

These extended success metrics are tracked via the generic conversion endpoint, documented below. Purchase conversions are tracked in collaboration with the Constructor client integration team using a separate endpoint.

Examples of events tracked with the generic conversion endpoint include:

  • Add to cart
  • Add to wishlist
  • Like
  • Send a message
  • Make an offer
  • Read

Log a conversion event#

To capture the diversity of use cases our customer base, we allow several different types of conversion to be communicated, and also allow logging of entirely custom conversion types.

To log a conversion event, simply specify the necessary conversion type and other required fields (documented below) while making a POST request to:


Log an event
curl -X POST -H 'Content-Type: application/json' \
-u '[your token]:' \
-d '{
"item_id": "brown_toy_poodle",
"search_term": "toy poodle",
"type": "add_to_cart",
"key": <your API key>,
"c": <client id>,
"i": <user id>,
"s": <session number>

The above command returns a 200 Success response on success.

JSON Pamareters#

keystringYesThe key of the index you'd like to log events for.
cstringYesClient id. The library responsible for making the request
istringYesUser id. An anonymized user identification hash.
sintegerYesSession number. The index for the session in which the conversion behavior occurred.
typestringNoType of conversion event (see options below). This defaults to add_to_cart if type is not specified in the request body.
display_namestringNoDisplay name for the conversion event. This display name will be shown on the dashboard in the future to clarify usage. It is required if the conversion event is custom (i.e. is_custom_type is set to true).
search_termstringNoSearch term associated with this conversion event.
is_custom_typebooleanNoSpecifies if the conversion type is a custom type event. This field needs to be set to true if you'd like to use custom event types.

Default types and display names#

If the conversion type is standard and display_name is not specfied in the request body, default display names will be used.

The mapping for standard conversion type to default display_name is as follows:

add_to_cartAdd to cart
add_to_wishlistAdd to wishlist
messageSend a message
make_offerMake an offer

Overriding these display names allows customers to reflect the language within their app or website more consistently - for instance if the UX in an app is "Add to basket" rather than add to cart, or "Ask seller a question" rather than "Send a message"

Custom Conversion events#

To use custom conversion events, specify "is_custom_type": True in the request body, then set a display_name and specify the type of conversion event you'd like to log.