> ## 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.
# Onboarding
> Offsite onboarding timeline, account architecture, and set up steps.
export const OffsiteVendorAccountArchitectureDiagram = () =>
;
};
## 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](#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](#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`](/en/api-reference/events/report-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.
```http theme={null}
POST /v2/events
```
```json theme={null}
{
"clicks": [
{
"occurredAt": "2023-11-07T05:31:56Z",
"opaqueUserId": "",
"id": "",
"entity": {
"id": "product1",
"type": "product"
},
"externalCampaignId": "",
"externalVendorId": "",
"dsp_metadata": {
"gclid": ""
},
"channel": "offsite"
}
]
}
```
#### Reporting purchases
All fields are required.
```http theme={null}
POST /v2/events
```
```json theme={null}
{
"purchases": [
{
"occurredAt": "2023-11-07T05:31:56Z",
"opaqueUserId": "",
"id": "",
"items": [
{
"productId": "product1",
"vendorId": "",
"unitPrice": 75.0,
"quantity": 1
},
{
"productId": "product2",
"vendorId": "",
"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
***