@font-face {
	font-family: Circular;
	font-style: normal;
	font-weight: bold;
	font-display: swap;
	src: url("https://docs.topsort.com/fonts/Circular/CircularStd-Bold.woff2") format("woff2");
}

@font-face {
	font-family: Circular;
	font-style: italic;
	font-weight: bold;
	font-display: swap;
	src: url("https://docs.topsort.com/fonts/Circular/CircularStd-BoldItalic.woff2") format("woff2");
}

h1, h2, h3, h4, h5, h6 {
    font-family: Circular, ui-sans-serif, sans-serif;
}

/* Logos same size as main docs site */
#navbar a[href="/"] img,
#navbar a[href="/"] img {
    max-width: 180px;
}

/* Hide the moved header nav on mobile and show on 'lg' screens */
#navbar > .max-w-8xl nav {
    display: none;
}

@media screen and (min-width: 1024px) {
    #navbar > .max-w-8xl nav {
        display: flex;
    }
}

/* Combined with the javascript, the below rules make the items the same order as on the main docs site */
#navbar > .max-w-8xl > div > div > div > div {
    justify-content: end;
}

#navbar > .max-w-8xl > div > div > div > div > .flex-1 {
    flex: none;
}

#navbar > .max-w-8xl > div > div > div > div > .ml-auto {
    margin-left: 0;
}

#navbar > .max-w-8xl > div > div > div > div > .mx-px {
    width: 25%;
    min-width: 120px;
}

#navbar > .max-w-8xl > div > div > div > div > div:first-child {
    margin-right: auto;
}

/* Hide the tabs bar */
#navbar > .max-w-8xl > div > .hidden {
    display: none;
}

/* Move up the sidebar because of hidden tabs */
#sidebar {
    top: 4rem;
}

/* Group headers in navigation sidebar look like the main docs site */
#navigation-items h5 {
    text-transform: uppercase;
    font-weight: normal;
    letter-spacing: 0.05em;
    font-size: 0.75rem;
    font-family: Inter, ui-sans-serif, sans-serif;
    color: rgb(134, 140, 152);
}

const logoContainer = document.querySelector("#navbar > .max-w-8xl > div > .relative > .flex > .h-full > div:first-child");
const navbar = document.querySelector("#navbar nav");
logoContainer.appendChild(navbar);

Starter Kit

API Reference

Integration Guide

Changelog

Knowledge Base

Report events

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.


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.


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.


RFC3339 formatted timestamp including UTC offset.

<p>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.
</p>
<p>
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.
</p>


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` 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.


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

The type of entity associated with the interaction.

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.


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.


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.


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.

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.


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


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


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`).


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


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.


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).


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.


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.


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.

The marketplace ID of the product being purchased.

The price of a single item in the marketplace currency.

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.


BearerAuth

Introduction

Learn how to authenticate with Topsort APIs using a bearer token

Authentication

Errors encountered when using Topsort's API endpoints

Errors

Logs

Learn how to use the auctions API to create auctions for listings and banners.

Running auctions

How to run an auction for a set of products

Set of products

Search

Combining winners and organic results

Banners

Carousels and Swimlanes

Landing pages

Attribution

Banner Attribution

Learn how to use the auctions API to create banner auctions for sponsored brands.

Banners for sponsored brands

Learn how to use the auctions API to create listing auctions for sponsored brands.

Listings

Listings for sponsored brands

Learn how to create an image, video, html, or json asset.

Creating an asset

Using webhooks

Learn about the event and payload specifications for webhooks.

Webhook event & payloads

Create auctions

Create sponsored brand auctions

Create Asset

Get Asset

Delete Asset

Update Asset

Get Assets

[BETA] Create Collection

[BETA] Get Collection

[BETA] Delete Collection

[BETA] Update Collection

[BETA] Get Collections

[BETA] Get Audiences

[BETA] Create Audience

[BETA] Get Audience

[BETA] Update Audience

[BETA] Delete Audience

Endpoint to get the credit limit for a marketplace.

Get Marketplace Credit Limit

Endpoint to set the credit limit for a marketplace.

Will truncate the input to its minimum denomination, e.g. USD 1,000.234 is USD 1,000.23 , as there is no fraction of a cent.

Set Marketplace Credit Limit

Endpoint to Get Vendor Charges.

Please note this is a beta API and therefore it is subject to change.

Get Vendor Charges

Endpoint to get the Account Activity for a vendor.

start_date and end_date timezone is optional, if no timezone is provided it will be converted to UTC timezone.

Get Vendor Account Activity

Endpoint to get the balance for a vendor.

Get Vendor Balance

Endpoint to add some balance for a vendor.

Will truncate the input to its minimum denomination, e.g. USD 1,000.234 is USD 1,000.23 , as there is no fraction of a cent.

Add Vendor Balance

Endpoint to burn some amount of balance for a vendor.

Burn Vendor Balance

Endpoint to get the credit History for a vendor.

Get Vendor Credit History

Endpoint to get the credit limit for a vendor.

Get Vendor Credit Limit

Endpoint to set the credit limit for a vendor.

Set Vendor Credit Limit

Endpoint to retrieve campaigns. Campaigns can be filtered by Vendor ID and status.

It is expected to use for getting all campaigns of a marketplace & all campaigns of a vendor in dashboards.
Filtering by status is expected to use at review page getting campaigns approved, pending tabs.

Get Campaigns

Endpoint to create a campaign with its respective budget and bids.

It is expected to use at all types of campaign creations.

Create Campaign

Endpoint to retrieve specific campaign by Campaign ID.

It is expected to use at Campaign Page.

Get Campaign By Id

Delete Campaign By Id

Endpoint to update fields for a given campaign.

Update Campaign By Id

Endpoint to retrieve all campaign's bids.

Get Campaign Bids

Create Campaign Bids

Delete Campaign Bid By Id

Update Campaign Bid By Id

Please note this is a beta API and therefore it is subject to change.

Get estimated clicks of a future campaign.

[BETA] Get estimated clicks of a future campaign for a given vendor

This endpoint returns paginated product ids currently in active campaigns.You can filter by vendor_id, fetching only from active campaigns and bids.

Get Products In Campaign

This endpoint is deprecated. Use /products-in-campaign instead.

Get Sponsored Products

Get multiple categories from the catalog.

Get Categories

Create or replace one or more categories in the catalog.

Upsert Categories

Delete one or more categories from the catalog.

Delete Categories

Get the number of categories in the catalog.

Get Categories Count

Get Category

Get Products

Upsert Products

Delete Products

Get the number of products in the catalog.

Get Products Count

Get Product

Get Vendors

Upsert Vendors

Delete vendors by ID.

This function won't error out when trying to delete vendors that don't exist.

Delete Vendors

Get Vendor

Invites a collection of Vendors to the Topsort platform.

The request payload should contain an array of pairs of vendor's ID, and
email.

[BETA] Invite Vendors

Provides a JWT token that allows to do operations on behalf of a vendor.

Get Vendor JWT

Endpoint to get a campaign's total behavioral summary report between given dates.

Get Campaign Report

Endpoint to get a campaign's daily behavioral summary report between given dates.

Get Campaign Daily Report

Endpoint to get a campaign's total behavioral summary report, divided by products, between given dates.

Get Campaign Report By Product

Endpoint to get a product's total behavioral summary report between given dates.

Get Product Report

Endpoint to get a product's daily behavioral summary report between given dates.

Get Product Daily Report

Endpoint to get a marketplace's total behavioral summary report between given dates.

Get Marketplace Report

Endpoint to get a marketplace's daily behavioral summary report between given dates.

Get Marketplace Daily Report

Endpoint to get a vendor's total behavioral summary report between given dates.

Get Vendor Report

Endpoint to get a vendor's daily behavioral summary report between given dates.

Get Vendor Daily Report

Get User By Email

Update a user vendor access. This will substitute accesses, so vendor ids not present in the update will be removed.

General

Auction examples

Asset examples

Webhook examples

Auctions

Events

Assets API

Audience API

Billing API

Campaign API

Catalog API

Invitation API

Modal API

Reporting API

User API

Webhooks API

Report events

Authorizations

Body