Report events

POST

/events

• Auctions v2 path

Authentication

Topsort’s APIs are authenticated via bearer tokens. Requests must include an authorization header containing your private API key.

Don't have an API key yet? Learn how to generate one.

Authorization

required

string

The header containing a private API key. Format this header as follows:

Authorization: Bearer <YOUR-API-KEY>

Request Body

Use the /events endpoint to notify Topsort about significant consumer interactions on the marketplace app:

• Impressions — a set of impressions means such promotables have become visible to the consumer.
• Clicks — a click is sent to Topsort when the consumer has clicked on a promotable.
• Purchases — a purchase is sent to Topsort once a consumer places an order.

For promoted interactions, include the resolvedBidId field from the /v2/auctions response. For unpromoted interactions, include the entity field to describe what was interacted with.

application/json

object

>= 1 properties

impressions

Array<object>

>= 1 items <= 50 items

An impression means a promotable has become visible to the consumer. For promoted entities, include the resolvedBidId field from the /v2/auctions response. For unpromoted entities, include the entity field to describe what was seen. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that’s also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns.

object

resolvedBidId

If the impression is over an ad promotion, this is the resolvedBidId field received from the /auctions request. In most situations, especially when reporting a sponsored interaction, you’ll want to fill in this field.

string

entity

Entity is meant for reporting organic events, not sponsored or promoted products. It refers to the object involved in the organic interaction. But, in most cases, you won’t need to fill in this object. Be aware that if resolvedBidId has any value, entity will be disregarded.

object

id

required

The marketplace’s ID of the entity associated with the interaction.

string

>= 1 characters

type

required

The type of entity associated with the interaction.

string

Allowed values: product vendor

placement

object

path

required

URL path of the page triggering the event.

For web apps, this can be obtained in JS using window.location.pathname.

For mobile apps, use the deep link for the current view, if available. Otherwise, encode the view from which the event occurred in your app as a path-like string (e.g. /root/categories/:categoryId).

string

>= 1 characters

position

For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.

integer

>= 1

page

For paginated pages, this should indicate which page number triggered the event.

integer

>= 1

pageSize

For paginated pages this should indicate how many items are in each result page.

integer

>= 1

productId

The ID of the product associated to the page in which this event occurred, if applicable. This ID must match the ID provided through the catalog service.

string

>= 1 characters

categoryIds

An array of IDs of the categories associated to the page in which this event occurred, if applicable. These IDs must match the IDs provided through the catalog service.

Array<string>

>= 1 items

searchQuery

The search string provided by the user in the page where this event occurred, if applicable. This search string must match the searchQuery field that was provided in the auction request (if provided).

string

>= 1 characters

occurredAt

required

RFC3339 formatted timestamp including UTC offset.

string format: date-time

opaqueUserId

required

The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.

If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.

string

>= 1 characters

id

required

The marketplace’s unique ID for the impression. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent.

string

>= 1 characters

additionalAttribution

If the marketplace wants to attribute an impression to an additional entity, they can use the additionalAttribution field. When using this field, the resolvedBidId must also exist in the event body.

object

id

required

The marketplace’s ID of the entity associated with the interaction.

string

>= 1 characters

type

required

The type of entity associated with the interaction.

string

Allowed values: product vendor

clicks

Array<object>

>= 1 items <= 50 items

A click is sent to Topsort when the consumer has clicked on a promotable. For promoted entities, include the resolvedBidId field from the /v2/auctions response. For unpromoted entities, include the entity field to describe what was clicked. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app.

object

resolvedBidId

If the click is over an ad promotion, this is the resolvedBidId field received from the /auctions request. In most situations, especially when reporting a sponsored interaction, you’ll want to fill in this field.

string

entity

Entity is meant for reporting organic events, not sponsored or promoted products. It refers to the object involved in the organic interaction. But, in most cases, you won’t need to fill in this object. Be aware that if resolvedBidId has any value, entity will be disregarded.

object

id

required

The marketplace’s ID of the entity associated with the interaction.

string

>= 1 characters

type

required

The type of entity associated with the interaction.

string

Allowed values: product vendor

placement

object

path

required

URL path of the page triggering the event.

For web apps, this can be obtained in JS using window.location.pathname.

For mobile apps, use the deep link for the current view, if available. Otherwise, encode the view from which the event occurred in your app as a path-like string (e.g. /root/categories/:categoryId).

string

>= 1 characters

position

For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.

integer

>= 1

page

For paginated pages, this should indicate which page number triggered the event.

integer

>= 1

pageSize

For paginated pages this should indicate how many items are in each result page.

integer

>= 1

productId

The ID of the product associated to the page in which this event occurred, if applicable. This ID must match the ID provided through the catalog service.

string

>= 1 characters

categoryIds

An array of IDs of the categories associated to the page in which this event occurred, if applicable. These IDs must match the IDs provided through the catalog service.

Array<string>

>= 1 items

searchQuery

The search string provided by the user in the page where this event occurred, if applicable. This search string must match the searchQuery field that was provided in the auction request (if provided).

string

>= 1 characters

occurredAt

required

RFC3339 formatted timestamp including UTC offset.

string format: date-time

opaqueUserId

required

The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.

If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.

string

>= 1 characters

id

required

The marketplace’s unique ID for the click. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no click model on the marketplace side, generate a unique string that does not change if the event is resent.

string

>= 1 characters

additionalAttribution

If the marketplace wants to attribute a click to an additional entity, they can use the additionalAttribution field. When using this field, the resolvedBidId must also exist in the event body.

object

id

required

The marketplace’s ID of the entity associated with the interaction.

string

>= 1 characters

type

required

The type of entity associated with the interaction.

string

Allowed values: product vendor

purchases

Array<object>

>= 1 items <= 50 items

A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign.

object

occurredAt

required

RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed. Please note that purchases will NOT be attributed to an auction that happened after.

string format: date-time

opaqueUserId

required

The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.

If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.

string

>= 1 characters

items

required

Items purchased.

Array<object>

>= 1 items

object

productId

required

The marketplace ID of the product being purchased.

string

>= 1 characters

quantity

Count of products purchased.

integer

default: 1 >= 1

unitPrice

required

The price of a single item in the marketplace currency.

number format: double

vendorId

The vendor ID of the product being purchased. This field is optional and should be filled in if a product is sold by multiple vendors.

string

>= 1 characters

id

required

The marketplace unique ID for the order. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no unique ID for orders on the marketplace side, generate a unique string that does not change if the event needs to be resent.

string

>= 1 characters

Responses

204

All events were reported successfully.

400

HTTP status codes as registered with IANA.

application/json

object

errCode

required

A short string uniquely identifying the problem.

string

Allowed values: bad_request empty_request internal_server_error invalid_api_key invalid_auction_id invalid_event_type invalid_promotion_type invalid_session missing_auctions missing_context missing_placement missing_product_id missing_promotion_type missing_purchased_at missing_session missing_slot_id missing_slots no_products no_purchase_items purchase_item_quantity_less_or_equal_than_zero resolved_bid_id_not_found too_few_impressions too_few_slots too_many_auctions

docUrl

A link to a documentation page providing more information about the error.

string format: uri

message

Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field.

string

401

Access token is missing or invalid