Ingest given event representing user's interaction.

post

https://api.perselio.com/api/v3/event

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

eventType

string

enum

required

Event type, it helps to identify what type of event body contains. Often it represents plugin name to which the event belongs.

Allowed:

eventAction

string

enum

required

Event action, defines what type of event body contains. Event is uniquely identified by combination of et and ea.

token

string

Front-end API authorization token. The token can be passed either as this query parameter or in the HTTP header Authorization: Zoe-Token <token>. Backend integrations may authenticate with Authorization: Basic <credentials> instead.

Body Params

This event is triggered when a user adds an item to their cart. It captures important data about the interaction, such as the specific item added, the quantity, and relevant product details. Note that this event should be logged whenever an item is successfully added to the cart, regardless of whether it occurs on a product page, category page, or any other location within the application. Exception is the list of search results in which you need to use addToCartSearch event.

eventAction

enum

Event type. Optional in case when set via query parameter (real time event api), mandatory
for the historical batch api.

eventType

enum

Event type. Use 'dr' for core recommendation events. Use 'ds' for search events.

ipAddress

string | null

IP address of client. Optional, filled only in case of backend-to-backend integrations.

zoeId

string

required

length ≥ 2

The zoeId field describes session or user's device and is retained for API compatibility.

clientTimestamp

number

required

≥ 0

Timestamp (as epoch milliseconds) when event occurred.

properties

object | null

JSON with additional properties not defined in our API, place here any information you find relevant.

userAgent

string

required

length ≥ 2

User agent description of client's browser (filled by browser).

userId

string | null

User identification - ID under which is user logged in system.

eventId

string | null

Id of the event set by client in the original event during event import. Only relevant for historical
event import, not relevant for the real-time event ingestion. Allows to map errors in the import batch
to particular event if set.

audienceId

string | null

Optional identifier of certain A/B testing group.
For example the field can help to distinct between standard session using
original site's recommendation and a session with a new prototype
recommendation.

messageVersion

string

Version of the message.

url

string | null

Full URL (including query parameters) on which the event was generated. Used mainly for analytical purposes.

recommendationId

string | null

Recommendation ID - identifier you retrieve from our recommendation API, used for providing our platform feedback about recommendation.

component

string | null

Describes the name of UI component from which the event
origins. The value can be either more general, e.g. the carousel, list, sidebar or
more concrete, e.g. HomepageCarousel, CartRecommendationsCarousel etc.
In case you are unable to identify the component, please use the 'default' keyword.

itemId

string

required

length ≥ 2

ID of item added to cart.

collection

string | null

The name or title of the section from which the event
origins. For example in the main list of product category the
collection represents the title of the category, e.g. "Ice
cream". Another example can be the carousel of featured products
where the collection should be equal to the text of displayed
heading above the carousel, e.g. "Featured products".

contextId

string | null

Optional raw placement or context correlation identifier. The default use case is an item ID, but this field is not normalized as item metadata. Do not send personal data, secrets, or customer-specific identifiers.

itemPrice

number | null

≥ 0

Price for single item.

price

number | null

≥ 0

Total price of item(s) added to cart, most of the time following formula applies: price = (itemPrice * quantity), but sale property can change it.

quantity

number | null

≥ 0

Number of items added to cart.

sale

number | null

0 to 1

Discount applied to given item, allow range <0,1>.

profit

number | null

Describes total potential profit when user buys item.

position

number | null

≥ 1

Describes item's position in list user clicked and triggers this event.

positionType

string | null

enum

Describes whether clicked item has anyhow been promoted or not.

Allowed:

pageNumber

integer | null

≥ 1

Number of the shown page. If the attribute is filled the 'position' attribute becomes relative.

pageSize

integer | null

≥ 1

Number of items per one page. Important information when 'pageNumber' attribute is sent.

Responses

200

400

Bad Request

401

Unauthorized

500

Internal Server Error