Introduction

This reference is generated from the Topsort openapi specification and includes quite a few operations.

However, only two are required for a typical integration.

A typical integration

1

Provide your catalog via a product feed.

2

(Have vendors create campaigns).

3

Run auctions via the API or using our clients.

The details will depend on your marketplace and needs. A selection of examples is available here.

4

Use one of the analytics libraries to report events.

Available API’s

Typical integrations will use these APIs:

• Auctions: Runs auctions in your marketplace.
• Events: Collects data on auction results.

For advanced integrations you might want to look at:

• Audiences: Manage audiences.
• Campaigns: Manage campaigns.
• Catalog: Manage products, categories and vendors.
• Billing: Manage vendor balances.
• Reporting: Read reports on marketplace, campaign or product performance.
• Invitations: Invite vendors to your marketplace.

URLs and redirects

To minimize the impact of auctions on your app’s performance, there is no redirect from URLs with a trailing slash (/). This is to avoid an extra round trip before auction winners are returned.

For example, when you want to run an auction, use /v2/auctions, not /v2/auctions/.

Using an URL with a trailing slash will result in a 404 Not Found error.

API Status

You can monitor and check API Status here.

Rate Limits

Topsort enforces rate limits on some of the endpoints to ensure that the quality of service is maintained for all users. The rate limits are different for the production and sandbox environments and are as follows:

Environment	Endpoint	Rate Limit
Sandbox	Catalog API	4 rps
Sandbox	Other Advanced APIs	5 requests every 2 seconds
Sandbox	Auctions and Events	No rate limit
Production	Catalog API	10 rps
Production	Other Advanced APIs	45 requests every 2 seconds
Production	Auctions and Events	No rate limit

Rate limit headers

Use these headers to navigate rate limits and when you can make another request:

• X-RateLimit-Limit - total number of requests allowed for the time period
• X-RateLimit-Remaining - remaining number of requests for the time period
• X-RateLimit-Reset - when you can make another request

How to handle rate limits

When you exceed the rate limit, you will receive a 429 Too Many Requests response. To handle this, you can implement a retry mechanism with an exponential backoff strategy. This will help you to avoid hitting the rate limit again.

Here is an example of how you can implement this in Typescript:

/**
 * Wraps `fetch()` with a retry function that respects retry limits from the API
 *
 * @param {string|URL} url
 * @param {RequestInit} request
 * @param {number} retries = 1
 * @returns {Promise<Response>}
 */
async function fetchWithRetry(url, request, retries = 1) {
  const response = await fetch(url, request);
  if (!response.ok) {
    if (response.status === 429) {
      // Handle rate limit
      const ms = response.headers.get("X-RateLimit-Reset");
      await new Promise((resolve) => setTimeout(resolve, ms));
      return fetchWithRetry(url, request, retries + 1);
    }
    throw new Error(`Failed to upload: ${response.status} ${await response.text()}`);
  }
}

OpenAPI Specification

The OpenAPI specification is available as a JSON file here.