> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Report events > Use the `/events` endpoint to report user interactions and activity in on a marketplace: - **Impressions** — a user viewed an asset. - **Clicks** — a user clicked on an asset. - **Purchases** — a user created an order. - **Page views** — a user visited a page. Interactions require either a `resolvedBidId`, for sponsored events coming from the `/v2/auctions` response, or an `entity` that describes the entity that was interacted with, in the case of organic or non-sponsored events. For analytics purposes, you can use the `placement` field to differentiate different listings or banners. For example, on a product page with a carousel of products, you can track impressions and clicks related to the carousel by including `/carousel` at the end of the `path` field in the `placement` object. This allows you to monitor the performance of carousel products in the [Data Room](https://docs.topsort.com/knowledge-base/analytics/data-room/). ## OpenAPI ````yaml /openapi.json post /v2/events openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /v2/events: post: tags: - Events summary: Report events description: > Use the `/events` endpoint to report user interactions and activity in on a marketplace: - **Impressions** — a user viewed an asset. - **Clicks** — a user clicked on an asset. - **Purchases** — a user created an order. - **Page views** — a user visited a page. Interactions require either a `resolvedBidId`, for sponsored events coming from the `/v2/auctions` response, or an `entity` that describes the entity that was interacted with, in the case of organic or non-sponsored events. For analytics purposes, you can use the `placement` field to differentiate different listings or banners. For example, on a product page with a carousel of products, you can track impressions and clicks related to the carousel by including `/carousel` at the end of the `path` field in the `placement` object. This allows you to monitor the performance of carousel products in the [Data Room](https://docs.topsort.com/knowledge-base/analytics/data-room/). operationId: reportEvents requestBody: description: Event data including impressions, clicks, purchases, and page views. content: application/json: schema: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EventsRequest required: true responses: '204': description: All events were reported successfully. '400': $ref: '#/components/responses/Topsort_Endpoints_v2_API_Reference_BadRequest' '401': $ref: >- #/components/responses/Topsort_Endpoints_v2_API_Reference_UnauthorizedError security: - Topsort_Endpoints_v2_API_Reference_HTTPBearer: [] components: schemas: Topsort_Endpoints_v2_API_Reference_EventsRequest: description: A batch request containing multiple events to be reported to Topsort. type: object additionalProperties: false minProperties: 1 properties: impressions: title: Impressions description: An array of impression events type: array minItems: 0 maxItems: 50 items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Impression' clicks: title: Clicks description: An array of click events type: array minItems: 0 maxItems: 50 items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Click' purchases: title: Purchases description: An array of purchase events type: array minItems: 0 maxItems: 50 items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Purchase' pageviews: title: Page views description: An array of page views type: array minItems: 0 maxItems: 50 items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_PageView' examples: - impressions: - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c occurredAt: '2019-01-01T12:59:59-05:00' opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 placement: path: /categories/dairy position: 1 page: 1 pageSize: 15 categoryIds: - 9BLIe resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= deviceType: mobile channel: onsite - clicks: - id: b39d39ed-ea0e-4059-9d15-4990b39c85a2 occurredAt: '2019-01-01T13:01:42-05:00' opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 placement: path: /categories/dairy position: 1 page: 1 pageSize: 15 categoryIds: - 9BLIe resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= deviceType: mobile channel: offsite - purchases: - id: 0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0 items: - productId: p_SA0238 unitPrice: 12.95 quantity: 2 vendorId: v_8fj2D - productId: p_oajf2D unitPrice: 1.49 occurredAt: '2019-01-01T12:59:59-05:00' opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 deviceType: desktop channel: onsite - id: b7147656-504f-4ae7-b335-740829ff64c6 items: - productId: p_SA0279 unitPrice: 119.95 quantity: 5 vendorId: v_8fj2D occurredAt: '2019-01-01T13:59:59-05:00' opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 channel: instore - pageviews: - id: 8f648a8e-830c-4bb4-9d93-6ea80075ca82 occurredAt: '2019-01-01T12:59:58-05:00' opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 page: type: category pageId: /categories/dairy value: dairy deviceType: mobile channel: onsite Topsort_Endpoints_v2_API_Reference_Impression: title: Impression type: object description: > 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. required: - occurredAt - opaqueUserId - id additionalProperties: false properties: resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID description: > 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. entity: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity' placement: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Placement' occurredAt: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' id: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier additionalAttribution: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' object: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_InteractionObject externalCampaignId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalCampaignId externalVendorId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalVendorId deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' channel: type: string description: Optional. The channel where the event occurred. enum: - onsite - offsite - instore examples: - onsite Topsort_Endpoints_v2_API_Reference_Click: title: Click description: > 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. type: object required: - occurredAt - opaqueUserId - id additionalProperties: false properties: resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID description: >- 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. entity: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity' placement: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Placement' occurredAt: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' id: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier additionalAttribution: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' object: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_InteractionObject clickType: type: string description: >- For sponsored events only, signals the specific interaction flavor with the listing. enum: - product - like - add-to-cart externalCampaignId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalCampaignId externalVendorId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalVendorId deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' channel: type: string description: Optional. The channel where the event occurred. enum: - onsite - offsite - instore examples: - onsite Topsort_Endpoints_v2_API_Reference_Purchase: title: Purchase description: > 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. type: object required: - occurredAt - opaqueUserId - items - id additionalProperties: false properties: occurredAt: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt' description: >- 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. opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' items: type: array description: Items purchased. minItems: 1 items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_PurchaseItem id: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' channel: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ChannelType' Topsort_Endpoints_v2_API_Reference_PageView: title: Page View type: object description: > A page view represents the navigation of the user throughout the page. They are considered organic events. In contrast to clicks or impressions, which are events within a page, a page view is the interaction with the full page, which can contain multiple objects. required: - occurredAt - opaqueUserId - id - page additionalProperties: false properties: page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' occurredAt: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' id: type: string description: > The marketplace's unique ID for the event. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no pageview model on the marketplace side, generate a unique string that does not change if the event is resent. minLength: 1 examples: - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' channel: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ChannelType' Topsort_Endpoints_v2_API_Reference_Error: description: >- Error response object containing error code, message, and documentation URL. type: object required: - errCode properties: errCode: type: string description: A short string uniquely identifying the problem. enum: - bad_request - empty_request - internal_server_error - invalid_api_key - invalid_auction_id - invalid_demand_source - invalid_event_type - invalid_external_bid - invalid_external_demand_ad_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 - too_many_external_bids - unauthorized_external_demand examples: - bad_request - no_products docUrl: type: string format: uri description: >- A link to a documentation page providing more information about the error. examples: - https://api.docs.topsort.com/reference/errors message: type: string description: > 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. examples: - could not find the provided resolved bid id Topsort_Endpoints_v2_API_Reference_ResolvedBidID: type: string description: An opaque Topsort ID to be used when this item is interacted with. examples: - >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= Topsort_Endpoints_v2_API_Reference_EventEntity: type: object description: > `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. required: - id - type additionalProperties: false properties: id: type: string description: The marketplace's ID of the entity associated with the interaction. minLength: 1 examples: - ean-512385132 type: type: string description: The type of entity associated with the interaction. enum: - product - vendor examples: - product Topsort_Endpoints_v2_API_Reference_Placement: description: Information about where an ad or product is placed on a page. type: object required: - path additionalProperties: false properties: path: type: string description: > 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`). minLength: 1 examples: - /categories/dairy position: type: integer description: > For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list. minimum: 1 page: type: integer description: > For paginated pages, this should indicate which page number triggered the event. minimum: 1 pageSize: type: integer description: > For paginated pages this should indicate how many items are in each result page. minimum: 1 examples: - 15 productId: type: string description: > 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. minLength: 1 categoryIds: type: array items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID' description: > 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. minItems: 1 searchQuery: type: string description: > 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). minLength: 1 examples: - blue shoes Topsort_Endpoints_v2_API_Reference_occurredAt: type: string format: date-time description: A RFC3339 formatted timestamp including UTC offset. examples: - '2009-01-01T12:59:59-05:00' Topsort_Endpoints_v2_API_Reference_OpaqueUserID: type: string description: >- The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests. examples: - 71303ce0-de89-496d-8270-6434589615e8 Topsort_Endpoints_v2_API_Reference_EventIdentifier: type: string description: > A unique identifier for the request. 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. minLength: 1 examples: - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c Topsort_Endpoints_v2_API_Reference_Page: description: Information about the page where an auction or event occurs. type: object title: Page required: - type - pageId properties: type: type: string enum: - home - category - PDP - search - cart - other description: Type of page. examples: - category value: oneOf: - type: string description: Detail of the page, depending on the type examples: - electronics - type: array items: type: string description: Only valid for type cart. Items on the cart examples: - coffee - cookies - apples minItems: 1 pageId: type: string description: Identifies the page examples: - /category/electronics Topsort_Endpoints_v2_API_Reference_InteractionObject: type: object description: Information regarding an organic or non-sponsored event. required: - type properties: type: type: string description: The type of object that is being reported on the interaction. enum: - listing - banner assetId: type: string description: When type is `banner`, signals the ID of the asset of the banner examples: - banner_asset_001 clickType: type: string description: >- When type is `listing`, signals the specific interaction flavor with the listing. enum: - product - like - add-to-cart Topsort_Endpoints_v2_API_Reference_ExternalCampaignId: type: string description: Marketplace provided ID for a campaign examples: - awareness-campaign-2025 Topsort_Endpoints_v2_API_Reference_ExternalVendorId: type: string description: Marketplace provided ID for a vendor examples: - my-new-vendor Topsort_Endpoints_v2_API_Reference_DeviceType: type: string description: The device the user is on. enum: - desktop - mobile examples: - mobile Topsort_Endpoints_v2_API_Reference_PurchaseItem: description: >- An item included in a purchase transaction with product, quantity, and pricing details. type: object required: - productId - unitPrice additionalProperties: false properties: productId: type: string description: The marketplace ID of the product being purchased. minLength: 1 examples: - p_SA0238 quantity: type: integer minimum: 1 default: 1 description: Amount of products purchased. examples: - 2 unitPrice: type: number format: double exclusiveMinimum: 0 description: The price of a single item in the marketplace currency. examples: - 12.95 vendorId: type: string description: > The vendor ID of the product being purchased. This field is optional and should be filled in if 1. a product is sold by multiple vendors, or 2. you want to use it for halo attribution minLength: 1 examples: - v_8fj2D Topsort_Endpoints_v2_API_Reference_ChannelType: type: string description: Optional. The channel where the event occurred. enum: - onsite - offsite - instore examples: - onsite Topsort_Endpoints_v2_API_Reference_CategoryID: type: string description: A category ID. minLength: 1 examples: - c_electronics responses: Topsort_Endpoints_v2_API_Reference_BadRequest: description: HTTP status codes as registered with IANA. content: application/json: schema: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Error' Topsort_Endpoints_v2_API_Reference_UnauthorizedError: description: Access token is missing or invalid securitySchemes: Topsort_Endpoints_v2_API_Reference_HTTPBearer: description: >- A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API. scheme: bearer type: http ````