Skip to main content

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.

This example demonstrates a full flow using Topsort’s APIs for a sponsored product campaign with category targeting. Replace API keys and IDs with your actual credentials and values. Steps:
1

Sync catalog

Sync your product catalog with Topsort
2

Create a campaign

Set up a sponsored product campaign
3

Send auction requests

Request auction winners
4

Track events

Report impressions, clicks, and purchases
5

Get report

Retrieve campaign performance data
  • For managing products, campaigns, and reports, use an Advanced API Key (TSC_…). - For auctions and events, use a Marketplace API Key (TSE_…).

​
1. Sync Catalog

A sample product example-product-coca-cola, from category soft-drinks is used in this example. Remember to use your Advanced API Key. 
const apikey = "TSC_...";

const body = {
  products: [
    {
      active: true,
      categories: ["soft-drinks"],
      id: "example-product-coca-cola",
      imageURL:
        "https://intl.cokestore.com/media/catalog/product/1/6/16181_squeeze-ko-can-maria-2.png",
      name: "Coca Cola can",
      price: "9.99",
      vendors: ["coca-cola"],
    },
  ],
};

try {
  const response = await fetch(
    "https://api.topsort.com/public/v1/catalog-search-service/catalogs/products",
    {
      method: "PUT",
      mode: "cors",
      headers: {
        Authorization: `Bearer ${apikey}`,
        "Content-Type": "application/json; charset=utf-8",
      },
      body: JSON.stringify(body),
    }
  );
  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

​
2. Create Campaign

In this example, a campaign is created to promote the product example-product-coca-cola, having a keyword trigger (soft drink). Remember to use your Advanced API Key. 
const apikey = "TSC_...";

const body = {
  bids: [
    {
      target: {
        type: "product",
        id: "example-product-coca-cola",
      },
      triggers: [
        {
          type: "keyword",
          value: {
            matchType: "exact",
            words: ["soft drink"],
          },
        },
      ],
    },
  ],
  budget: {
    type: "daily",
    amount: 10000,
  },
  campaignType: "autobidding",
  isActive: true,
  status: "approved",
  adFormat: "listing",
  name: "An example campaign",
};

try {
  const response = await fetch(
    "https://api.topsort.com/public/v1/campaign-service/campaigns?vendor_id=demo-vendor",
    {
      method: "POST",
      mode: "cors",
      headers: {
        Authorization: `Bearer ${apikey}`,
        "Content-Type": "application/json; charset=utf-8",
      },
      body: JSON.stringify(body),
    }
  );
  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

​
3. Send Auction Request

In this example, an auction request is created to return winners triggered by the search term “soft drink”. Remember to use your Marketplace API Key. 
const apikey = "TSE_...";

const body = {
  auctions: [
    {
      searchQuery: "soft drink",
      slots: 1,
      type: "listings",
    },
  ],
};

try {
  const response = await fetch("https://api.topsort.com/v2/auctions", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

​
4. Tracking Events

In this example, a click on a promoted product is tracked using our API. The resolvedBidId of the winner returned by the auctions call needs to be sent in the body of the request, to guarantee correct attribution of sales. Remember to use your Marketplace API Key. 
const apikey = "TSE_...";

const body = {
  clicks: [
    {
      id: "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
      occurredAt: "2024-07-23T11:49:04+00:00",
      opaqueUserId: "71303ce0-de89-496d-8270-6434589615e2",
      resolvedBidId:
        "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw",
    },
  ],
};

try {
  const response = await fetch("https://api.topsort.com/v2/events", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}