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.

​
Overview

To launch offsite ads for a particular platform, the marketplace grants Topsort access to required ad accounts, implements offsite event tracking, and Topsort handles the rest of the integration (for example, syncing catalog and offline events with the marketplace, validation). Topsort runs a 2-week implementation timeline for each offsite platform (for example, Google or Meta) to ensure a successful POC launch, supported by dedicated cross-functional resources from the client:
  • Engineering: ~1 day of effort from a marketplace engineer (integration and validation). Development can likely be completed on a single 90-minute call with Topsort engineers.
  • Ad Operations: ~1 day of marketplace ad ops support for campaign setup, QA, and launch.

​
Account architecture

Automated account provisioning scales to thousands of vendors with clear budget separation and minimal manual setup. Below is the recommended account structure.

​
Google

  • Marketplace provides: Access to MCC (Manager account) + MCA (Merchant Center multi-client account)
  • Topsort creates: Vendor Google Ads accounts with required Merchant Center linking

​
Meta

  • Marketplace provides: Access to Parent Business Manager
  • Topsort creates: Child Business Manager and ad account per vendor

​
TikTok

  • Marketplace provides: Access to TikTok Business Center / Business Manager, with permission to manage advertiser accounts and assets
  • Topsort creates: A dedicated TikTok ad account for the Topsort offsite integration, typically one ad account for the marketplace/retailer, not one per vendor

​
Snap

  • Marketplace provides: Access to Snap Business Manager / Organization, with permission to manage ad accounts and billing/assets
  • Topsort creates: A dedicated Snap ad account for the Topsort offsite integration, typically one ad account for the marketplace/retailer, not one per vendor

​
Set up steps

​
Account set up

​
Account access (marketplace)

The marketplace grants Topsort admin access to the top-level ad platform accounts required for the channels being onboarded. See Account architecture above for the specific accounts to grant access to on each platform.

​
Account creation (Topsort)

Topsort provisions the vendor-level account structure under those marketplace containers, including any child ad accounts, business managers, or merchant center accounts needed for the integration. See Account architecture above for what Topsort creates on each platform. The marketplace can provide Topsort with a list of vendors to enable for offsite.

​
Catalog sync (Topsort)

Where catalog-based offsite formats are in scope, Topsort syncs the marketplace catalog to the offsite platform, mapping each vendor’s products into the corresponding platform account structure for that vendor.

​
Event tracking set up (marketplace)

The only area where the marketplace will need to do development is event tracking. To report events for offsite, use the same /v2/events endpoint as onsite events, passing additional parameters in the request body.

​
Opaque user ID

The same opaqueUserId used for onsite events should also be reused for offsite attribution. No separate offsite identifier is required. Topsort needs a persistent, privacy-safe user identifier to connect clicks and purchases across channels. The same onsite requirements apply to offsite usage:
  • Persistence: Should remain stable for the attribution window (typically 7–30 days).
  • Consistency: The same user should receive the same ID across visits and channels when possible.
  • Privacy-safe: Must not contain PII such as email, phone number, or name.

​
Click URL

The URL that the user has when they land on your site from an offsite ad click will have important query params attached. Example click URL: 
https://www.retailer.com/search?q=shampoo&
externalCampaignId=9d2d7d7d-5d4f-4d8e-a8d0-2d7a6f9c1234&
externalVendorId=vendor_abc123&
gclid=CjwKCAj_example123&
utm_source=google&
utm_medium=c
Query params:
  • gclid — click ID attached by Google
  • externalCampaignId and externalVendorId — query params containing the Topsort campaign ID and vendor ID, attached by Topsort. Should persist alongside the user attribution state for at least the duration of the attribution window (configurable 7–30 days). They should survive navigation and repeat visits so subsequent purchase events can be correctly tied back to the originating offsite ad click.

​
Reporting clicks

Send the below event when a user lands on your site from an offsite ad click. All fields are required. 
POST /v2/events

{
  "clicks": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "entity": {
        "id": "product1",
        "type": "product"
      },
      "externalCampaignId": "<Topsort UUID>",
      "externalVendorId": "<Topsort externalVendorId>",
      "dsp_metadata": {
        "gclid": "<Google click ID>"
      },
      "channel": "offsite"
    }
  ]
}

​
Reporting purchases

All fields are required. 
POST /v2/events

{
  "purchases": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "items": [
        {
          "productId": "product1",
          "vendorId": "<externalVendorId>",
          "unitPrice": 75.0,
          "quantity": 1
        },
        {
          "productId": "product2",
          "vendorId": "<externalVendorId>",
          "unitPrice": 25.0,
          "quantity": 1
        }
      ]
    }
  ]
}

​
Sharing events to offsite platforms

The client does not need to separately report conversion events to the offsite platform. Topsort automatically sends eligible purchase events tied to the corresponding click ID (for example, Google Click ID or GCLID) through the platform’s offline Conversions API.

​
Onboarding schedule

​
Week 1 – Access & event tracking setup

  • Grant access to required accounts
  • Initiate event tracking implementation
  • Sync catalog if needed to offsite platform
  • Begin initial system configuration

​
Week 2 – Integration & data setup

  • Finish integration and begin testing
  • Validate event tracking and catalog structure/quality
  • Once everything is set up, validate with a live campaign and monitor performance