@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);


Logs

Starter Kit

Introduction

Learn how to authenticate with Topsort APIs using a bearer token

Authentication

Errors encountered when using Topsort's API endpoints

Errors

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

Running auctions

Learn how to use the Sponsored Brands auctions API to create auctions for brand promotions.

Creating an asset

Using webhooks

Learn about the event and payload specifications for webhooks.

Webhook event & payloads

Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of 
sponsored listing auctions and banner auctions. Each auction type has a unique body schemas.


Create auctions

Create sponsored brand auctions

Use the `/auctions/travel` endpoint to create batch auctions for sponsored travel listings. We support two types of sponsored travel listings, hotels and flights. Each batch of auction requests can be a combination of sponsored hotel and flight listing auctions. Each auction type has a unique body schemas.

Create travel auctions

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.

Interactions require either a `resolvedBidId` from the `/v2/auctions` response or an `entity` that describes 
the entity to attribute.

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


Report events

Use the `/events/beta/link-users` endpoint to report to Topsort linked opaque user IDs.

This endpoint allows linking two opaque user IDs for attribution purposes. The `from` field represents the 
original opaque user ID, and the `to` field represents the target opaque user ID to be linked. The request 
will fail if the `from` and `to` opaque user IDs are the same.

Contact your sales representative to gain access to this endpoint and start using it.


[Beta] Report Link Users

Rank objects

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

Endpoint to get all the billing contacts.

Get Billing Contacts

Get Billing Contact

Upsert Billing Contact

Endpoint to get a billing contact campaign.

Get Campaign Billing Contact

Endpoint to upsert a billing contact campaign.

Upsert Campaign Billing Contact

Endpoint to get the credit limit for a marketplace.

This endpoint has been deprecated and now it returns 0 for all
marketplaces.

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.

This endpoint is a no-op as marketplace credit limit has been removed.

Set Marketplace Credit Limit

Endpoint to assign a billing contact to a vendor.

Upsert Vendor Billing Contact

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.

This endpoint has been deprecated and now it returns the marketplace credit
limit for all vendors.

Get Vendor Credit Limit

Endpoint to set the credit limit for a vendor.

This endpoint is a no-op as vendor credit limit has been removed.

Set Vendor Credit Limit

Endpoint to unassign a billing contact from a vendor.

Delete Vendor Billing Contact

Endpoint to list all the wallets of a vendor.

Get Vendor Wallets

Endpoint to create a wallet for a vendor.

There is a limit of 3 Wallets per vendor.

Create Wallet

Endpoint to change the balance for a wallet. It

will add the amount to the wallet if the amount is positive and burn the amount if it is negative.
The amount is ISO 4217 currency code compliant meaning that 100 as an input for USD marketplace will be 1 USD.

Adjust Wallet Balance

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

Update 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

Get interactions report for a marketplace grouped by entity type.

This endpoint returns detailed interaction data (impressions, clicks, purchases, etc.)
aggregated by the specified entity type (vendor, campaign, or product) and time granularity (daily or hourly).
The response is paginated to handle large datasets.

Get Marketplace Interactions Report

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

Get Marketplace Report

Get KPIs for campaigns in a marketplace using external vendor IDs.

Get Marketplace Campaigns Kpis

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

Get Marketplace Daily Report

Get KPIs for vendors in a marketplace using external vendor IDs.

Get Marketplace Vendors Kpis

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

[BETA] Retrieve a list of segments.

Upsert segments with the provided information.

[BETA] Upsert segments with the provided information.

[BETA] Delete a segment.

Retrieve a signed URL for uploading a segment user file.

This endpoint returns a pre-signed URL that allows you to securely upload a segment user file.

File requirements:
- The file must be in plain text format (".txt").
- It should not contain headers.
- Each line must represent a single opaque user ID.

The signed URL can be used to upload the file directly via an HTTP PUT request.

Returns
-------
    dict: A dictionary containing the signed URL and any additional metadata required for upload.

[BETA] Get upload users signed url for a segment.

Retrieve the balance of a specific agency account.

[BETA] Get Agency Account Balance

Retrieve the top-ups of a specific agency account.

[BETA] Get Agency Account Top-ups

Retrieve a list of campaigns associated with a specific account.

[BETA] Get Toppie Campaigns

Create a new agency campaign with the provided details.

[BETA] Create Toppie Campaign

Retrieve configuration details for a specific campaign.

[BETA] Get Toppie Campaign Details

Update an agency campaign with the provided details.

[BETA] Update Toppie Campaign

Retrieve bidding data for a specific campaign.

[BETA] Get Toppie Campaign Bids

Retrieve a list of products associated with a specific account.

List Account Products

Retrieve a general report for an account.

Get Agency Account Report

Get Agency Account Activity

Retrieve a list of campaigns and their reports.

Get Agency Account Campaigns

Retrieve reports for multiple campaigns using their IDs.

Get Account Campaigns By Ids

Retrieve a detailed report for a specific campaign.

Get Agency Campaign Report

Retrieve a product-level report for a specific campaign.

Get Campaign Report Per Product

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

Toptimize

Assets API

Billing API

Campaign API

Catalog API

Invitation API

Modal API

Reporting API

Segments Service

Toppie API

User API

Webhooks API

Logs