Transferring Website Behavior Data via REST API
Send the user behavior data and use it to create personalized product recommendations for the site and for your emails.
You can send events through one of the methods:
- Using eS.JS;
- Using REST API.
Important
When setting up tracking via the REST API, the recommendations functionality on the site will not be available, in this case, you need to use the option of calling eS.JS functions
In this article, we will explain how to use the second method.
Request headers
POST / HTTP/1.1
Host:
https://tracker.yespo.io/api/v2
Content-type: application/json
Response status code is 200: No authorization is required.
ProductPage
Description
To display correct recommended products or product categories or send triggers for abandoned browses, send a request with data on:
- Product card the user is currently viewing;
- Product price and availability.
Example
{
"GeneralInfo": {
"eventName": "ProductPage",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"ProductPage": {
"Product": {
"productKey": "72354",
"price": "754 USD",
"isInStock": "1",
"tag_something": [
"abc",
"bca"
]
},
"Tags": {
"some_tags": [
"some_tag1",
"some_tag2"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “ProductPage” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact our support team. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in the Yespo |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc” |
datetime | 1579622183208 | Timestamp (millisecond) |
ProductPage | Required | Event description |
productKey | “72354” | • Product ID. |
price | “754 USD” | The price per item can be sent with the currency value. If the price has changed on the site but hasn’t changed in the feed, the sent value will be the value from the site. |
isinStock | “1” | • Indicates if items are in stock. |
tag_[something] | ["abc","bca"] | • All additional fields can be transferred in this parameter. The prefix tag_ is required. After it, you can enter any name. |
Tags | Optional | Additional fields |
StatusCart
Description
An event is sent after the cart status (with a new GUID) is changed, for example, after clicking a Buy button on the category page. The cart status should be updated from all pages. If the cart is empty, then you need to send an empty cart event (empty array without products).
Example
{
"GeneralInfo": {
"eventName": "StatusCart",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"StatusCart": {
"GUID": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
"Products": [
{
"productKey": "430738",
"price": 201.95,
"discount": 180,
"quantity": 1,
"price_currency_code": "USD",
"tag_something": [
"aaa",
"bbb"
]
},
{
"productKey": "902339",
"price": 596,
"discount": 590,
"quantity": 1,
"price_currency_code": "USD",
"tag_something": [
"aaa",
"bbb"
]
}
],
"Tags": {
"some_tags": [
"1",
"a2"
],
"some_tags1": [
"4",
"gg"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “StatusCart” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact our support. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in the platform |
datetime | 1579622183208 | Timestamp (millisecond) |
GUID | “6F9619FF-8B86-D011-B42D-00CF4FC964FF” | • Displays the current composition of the shopping cart |
StatusCart | Required | • Event description. |
productKey | “430738” | • Product ID. |
price | “201.95” | Price per item |
discount | “180” | Discount per item |
quantity | “1” | Quantity of items |
price_currency_code | “USD” | Currency |
tag_[something] | ["abc","bca"] | • All additional fields can be transferred in this parameter. The prefix tag_ is required. After it, you can enter any name. |
Tags | Optional | Additional fields |
Wishlist
Description
Sending the AddToWishlist event - at the time of adding a product to the wish list (favorites).
Necessary for calculating and displaying recommendations and sending triggers related to the wish list.
Example
{
"GeneralInfo": {
"eventName": "AddToWishlist",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"AddToWishlist": {
"Product": {
"productKey": "72354",
"price": "754",
"isInStock": "1",
"tag_something": [
"abc",
"bca"
]
},
"Tags": {
"some_tags": [
"some_tag1",
"some_tag2"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required Type: object | General information |
eventName | “AddToWishlist” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact our support team. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" Type: string | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in the Yespo |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script. You can get on the site. |
datetime | 1579622183208 | Timestamp (millisecond) |
AddToWishlist | Required | Event description |
productKey | “72354” | • Product ID. |
price | “754 USD” | The price per item. |
tag_[something] | ["abc","bca"] | • All additional fields can be transferred in this parameter. The prefix tag_ is required. After it, you can enter any name. |
Tags | Optional | Additional fields |
PurchasedItems
Description
To display recommendations on the order confirmation page or to send triggers for abandoned carts, you need to send a request that will indicate which product the user purchased.
Example
{
"GeneralInfo": {
"eventName": "PurchasedItems",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"PurchasedItems": {
"Products": [
{
"product_id": "430738",
"unit_price": "201.95",
"quantity": 1
},
{
"product_id": "211452",
"unit_price": "341.80",
"quantity": 2
}
],
"OrderNumber": "123/2017",
"Tags": {
"some_tags1": [
"4",
"gg"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “StatusCart” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact our support. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in the Yespo |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc” |
OrderNumber | “123/2017” | • Order number. |
PurchasedItems | Type: array of strings | List of items |
product_id | “430738” | Product ID. |
unit_price | “201.95” | Price per item |
quantity | “1” | Quantity of items |
Tags | Optional | Additional fields |
ProductImpressions
Description
The event that transfers data on the block display. It’s sent by default through JS API. You don’t need to send it additionally. If the script is not installed, transfer according to the format.
Example
{
"GeneralInfo": {
"eventName": "ProductImpressions",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"ProductImpression": {
"Products": [
{
"product_id": "430968",
"container_type": "1253"
},
{
"product_id": "430738",
"container_type": "1254"
},
{
"product_id": "429983",
"container_type": "1255"
}
],
"Tags": {
"some_tags": [
"1",
"a2"
],
"some_tags1": [
"4",
"gg"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “ProductImpressions” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact our support. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" | Phone number in the international format |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in our platform |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc” |
ProductImpressions | Required | • Description of impressions |
product_id | “430738” | ID of the product or category that is in the feed |
container_type | “1253” | Recommendation block number. You can get the container_type in response to a request for recommendations |
Tags | Optional | Additional fields |
CategoryPage
Description
Can be used to send data on:
- Triggers;
- Category browses without product card viewing;
- Site browses without category or product card viewing.
You need to send a request with the data on the category the user is currently browsing.
Example
{
"GeneralInfo": {
"eventName": "CategoryPage",
"siteId": "8A412DC",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "255830499",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"CategoryPage": {
"Category": {
"categoryKey": "509876"
},
"Tags": {
"some_tags": [
"1",
"a2"
],
"some_tags1": [
"4",
"gg"
]
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “ProductPage” | Event name |
siteId | “8A412DC” | • To get your site ID, please contact support. |
externalCustomerId | "1234509876" Type: string | External identifier generated in your system |
user_phone | "1-541-754-3010" | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User’s name and surname |
user_es_contact_id | "255830499" | User ID in the Yespo |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc” |
CategoryPage | Required | Event description |
categoryKey | “Babies” | ID of the product or category according to a product feed |
Tags | Optional | Additional fields |
CustomerData
Description
To send triggers for abandoned browses or abandoned carts, you need to send a request with the data on the user.
Email should be sent at least in the personal account, on the page "Thank you for the order" and during registration.
Example
{
"GeneralInfo": {
"eventName": "CustomerData",
"siteId": "8D3869C",
"datetime":1579622183208,
"externalCustomerId": "1234509876",
"user_phone": "3801111111111",
"user_email": "[email protected]",
"user_es_contact_id": "255830499",
"user_name": "Johny",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3CGGG1"
}
}
}
Parameters
Name | Example | Description |
---|---|---|
GeneralInfo | Required | General information |
eventName | “StatusCart” | Event name |
siteId | “8A412DC” | To get your site ID, please contact support. |
externalCustomerId | "1234509876" | External identifier generated in your system |
user_phone | "1-541-754-3010" Type: string | Phone number in the international format |
user_email | " | User email |
user_name | "Gregori Boczynski" | User name and surname |
user_es_contact_id | "255830499" | User ID in the platform |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" | Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc” |
SearchRequest
Description
To collect statistics on search queries, you need to send the value from the search line.
Use this event for triggers. Send it only if the search returned no results. In the trigger, such contacts will receive personal recommendations (at the moment, recommendations don’t depend on the value entered in the search, we will support this feature in the nearest future).
Example
{
"GeneralInfo": {
"eventName": "SearchRequest",
"siteId": "CE460EC",
"datetime": 1668792552000,
"externalCustomerId": "1234509876",
"user_phone": "1-541-754-3010",
"user_email": "[email protected]",
"user_name": "Gregori Boczynski",
"user_es_contact_id": "",
"cookies": {
"sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
}
},
"SearchRequest": {
"search": "input_value",
"isFound": 1
}
}
Parameters
Name | Example | Description |
---|---|---|
search | "Coffe" | Value from the search string. What we are looking for on the site. |
isFound | 1/0 | If the list is empty, it returns 0 otherwise 1 |
ProductUpdate
Description
ProductUpdate is an optional event that updates product data in Yespo in real-time, regardless of the scheduled feed update. Pass product properties that need constant updating — price, discount, availability, etc.
Example
{
"GeneralInfo": {
"eventName": "ProductUpdate",
"siteId": "site_id"
},
"ProductUpdate": [
{
"brand": "Apple",
"name": "iPhone 7",
"description": "Some description",
"product_id": "430738",
"imgurl": "https://domain.com/apple/product_large.png",
"url": "https://domain.com/apple/product_page_example.html",
"unit_price": "201.95",
"isInStock": "1",
"tag_discount": ["10"],
"tag_oldprice": ["224.38"],
"price_currency_code": "UAH",
"category_id": ["3"],
"tag_something": [
"aaa",
"bbb"
]
},
{
"brand": "Apple",
"name": "iPhone 7",
"description": "Some description",
"product_id": "430738",
"imgurl": "https://domain.com/apple/product_large.png",
"unit_price": "201.95",
"isInStock": "1",
"tag_discount": ["10"],
"tag_oldprice": ["224.38"],
"price_currency_code": "UAH",
"category": "level1 > level2 > level3",
"category_id": ["1", "2", "3"],
"tag_something": [
"aaa",
"bbb"
]
}
]
}
Parameters
Name | Example | Description |
---|---|---|
ProductUpdate | Required | An array of updated products and their parameters |
siteId | site_id | Site name |
product_id | 430738 | Product ID |
isInStock | 1 | • Indicates if items are in stock. |
unit_price | 201.95 | Unit price |
description | Some description | Product description |
name | iPhone 7 | Product name |
imgurl |
| Image URL |
url |
| Product page URL |
brand | Apple | Brand name |
tag_discount | 10 | Discount |
price_currency_code | UAH | Price currency code |
tag_oldprice | 224.38 | Old price |
If the product has a discount, you can pass the next parameters:
{
"product_id": "1111",
"unit_price": "270",
"isInStock": 1,
"price_currency_code": "UAH",
"tag_oldprice": [
"300"
],
"tag_discount": [
"10"
]
}
And if the product has not a discount, than:
{
"product_id": "1111",
"unit_price": "270",
"isInStock": 1,
"price_currency_code": "UAH"
}
Updated about 10 hours ago