guides

v1 migration guide

This guide supports Topsort users that still use either the /v1/auctions or /v1/events endpoints with migrating to the new endpoints. If you are new to Topsort, please refer to the V2 Docs.

Notable new features

The v2 endpoints have many new features over v1, surpassing it both in usability and performance.

Some of the new features in v2 include:

Auctions
- Sponsored Brands
- Sponsored Banners
- Keyword-based targeting
- Category-based targeting
- Location Segmentation
- Audience Segmentation
- Batching up to 5 auctions in one request.
- No session needed
Events
- Batching
- No session needed
- Banner attribution

Migration steps

Auctions

1. Update the API endpoint

The V2 API endpoint is https://api.topsort.com/v2/auctions.

2. Update the request body

The request body structure has changed. Refer to the V2 Docs for the new structure.

Example V1 request body:

{
  "slots": 4,
  "products": [
    { "productId": "product_id1", "quality": 0.1 },
    { "productId": "product_id2", "quality": 0.2 }
  ],
  "session": {
    "sessionId": "session_id"
  },
  "geoTargeting": {
    "location": "georgia"
  },
}

Gets updated to V2 request body:

{
  "auctions": [
    {
      "type": "listings",
      "slots": 4,
      "products": {
        "ids": ["product_id1", "product_id2"],
        "qualityScores": [0.1, 0.2]
      },
      "geoTargeting": {
        "location": "georgia"
      }
    }
  ]
}

The changes are the following:

auctions array replaces the root object.
type field is added to specify the auction type. listings, and banners are supported.
products object replaces the products array.
quality field is replaced by qualityScores array.
geoTargeting object stays the same.
session object is removed. No session is needed in V2.

3. Update the response

The response structure has changed. Refer to the V2 Docs for the new structure.

Example V1 response:

{
  "slots": {
    "listings": {
      "auctionId": "AKFU78",
      "winners": [
        { "productId": "product_id1", "rank": 1, "winnerType": "product", "resolvedBidId": "WyJiX01" },
        { "productId": "product_id2", "rank": 2, "winnerType": "product", "resolvedBidId": "WyJiX02" }
      ]
    }
  }
}

Example V2 response:

{
  "results": [
    {
      "resultType": "listings",
      "winners": [
        { "id": "product_id1", "rank": 1, "type": "product", "resolvedBidId": "WyJiX01", "campaignId": "0191e74f-c3a2-7353-9a18-44912ee5213f" },
        { "id": "product_id2", "rank": 2, "type": "product", "resolvedBidId": "WyJiX02", "campaignId": "0191e74f-c3a2-7353-9a18-44912ee5213f" }
      ]
    }
  ]
}

The changes are the following:

results array replaces the root object.
resultType field is added to specify the auction type. listings, and banners are supported, depends on the request.
productId field is replaced by id.
winnerType field is replaced by type.
auctionId is removed in favor of resolvedBidId.
campaignId is added to specify the winning campaign

Events

1. Update the API endpoint

The V2 API endpoint is https://api.topsort.com/v2/events.

2. Update the request body

The request body structure has changed. Refer to the V2 Docs for the new structure.

Example V1 request body:

{
  "eventType": "Click",
  "session": {
    "sessionId": "session_id"
  },
  "placement": {
    "page": "product_detail",
    "location": "top"
  },
  "productId": "product_id",
  "auctionId": "auction_id",
  "id": "event_id",
  "occurredAt": "2021-01-01T00:00:00Z",
  "resolvedBidId": "resolved_bid_id"
}

{
  "eventType": "Impression",
  "session": {
    "sessionId": "session_id"
  },
  "placement": {
    "page": "product_detail",
    "location": "top"
  },
  "productId": "product_id",
  "auctionId": "auction_id",
  "id": "event_id",
  "occurredAt": "2021-01-01T00:00:00Z",
  "resolvedBidId": "resolved_bid_id"
}

{
  "eventType": "Purchase",
  "session": {
    "sessionId": "session_id"
  },
  "productId": "product_id",
  "auctionId": "auction_id",
  "id": "event_id",
  "purchasedAt": "2021-01-01T00:00:00Z",
  "items": [
    {
      "productId": "product_id",
      "quantity": 1,
      "auctionId": "auction_id",
      "unitPrice": 10000,
      "resolvedBidId": "resolved_bid_id"
    }
  ]
}

Gets updated to V2 request body:

{
  "clicks": [
    {
      "placement": {
        "page": "product_detail",
        "location": "top"
      },
      "entity": {
        "type": "product",
        "id": "product_id"
      },
      "id": "event_id",
      "occurredAt": "2021-01-01T00:00:00Z",
      "resolvedBidId": "resolved_bid_id",
      "opaqueUserId": "opaque_user_id"
    }
  ],
  "impressions": [
    {
      "placement": {
        "page": "product_detail",
        "location": "top"
      },
      "entity": {
        "type": "product",
        "id": "product_id"
      },
      "id": "event_id",
      "occurredAt": "2021-01-01T00:00:00Z",
      "resolvedBidId": "resolved_bid_id",
      "opaqueUserId": "opaque_user_id"
    }
  ],
  "purchases": [
    {
      "id": "event_id",
      "occurredAt": "2021-01-01T00:00:00Z",
      "opaqueUserId": "opaque_user_id",
      "items": [
        {
          "productId": "product_id",
          "quantity": 1,
          "unitPrice": 100.00,
          "vendorId": "vendor_id",
        }
      ]
    }
  ]
}

The changes are the following:

clicks, impressions, and purchases arrays replace the root object.
eventType field is removed. The event type is specified by the array name.
entity object replaces the productId field. Now an event can be related to a product, a vendor or a brand.
auctionId field is removed in favor of the resolvedBidId.
opaqueUserId field is added replacing the session object.
Purchases don’t need to specify neither auctionId nor resolvedBidId anymore.
Purchases ‘unitPrice’ is expressed on regular currency units (100.00) instead of minor units (10000).