Attribution and Billing

Attribution logic, conversion tracking, and payment models for Offsite Ads.

Attribution and conversion tracking

Your conversion-tracking setup determines how sales are attributed to ads and which metrics are available in Topsort.

For an overview of the integration choices, see Conversion tracking.

Topsort in-house attribution

When your marketplace sends click and purchase events to Topsort, Topsort can attribute purchases to ads using its in-house attribution.

You can apply the same attribution window and configuration across supported advertising platforms, enabling apples-to-apples comparisons of sales and return on ad spend (ROAS).

Sending events to Topsort does not automatically mean every advertising platform receives them. For some advertising platforms, including Google, Topsort forwards eligible conversions. Other advertising platforms require separate conversion sharing to support conversion optimization.

See Implement offsite event tracking with Topsort for implementation instructions.

Advertising platform attribution

When your marketplace sends conversions directly to an advertising platform, Topsort retrieves the resulting reports and displays them in its UI.

These metrics follow the advertising platform’s attribution methodology. Differences in attribution windows and settings can affect comparisons across advertising platforms.

Topsort’s in-house attribution is not required for the offsite integration to work.

Billing Model

Offsite billing is marketplace-controlled and consolidated:

• Vendors spend against channel-specific wallet capacity (for example, Google wallet, Meta wallet, Snapchat wallet, TikTok wallet, or Universal Ads wallet).
• Marketplace is billed directly by the channel for media spend.
• Marketplace bills vendors according to its commercial terms.

Payment Modes

• Prepay: vendor funds wallet credits before spending.
• Postpay: marketplace sets vendor spending capacity limits; charges are settled later.

Implement offsite event tracking with Topsort

This section is intended for developers, such as frontend developers implementing event tracking. It explains how to send marketplace click and purchase events to Topsort for in-house attribution.

Report offsite events through the same /v2/events endpoint used for onsite events, with the additional offsite parameters shown below.

The example click URL and click payload below illustrate Google click tracking. They are not an OpenAI or Universal Ads conversion-integration specification.

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
        }
      ]
    }
  ]
}

---