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.

Attribution connects ad interactions (impressions, clicks) to purchases. When a purchase doesn’t attribute, it’s usually one of these reasons:

​
Quick Checklist

CheckHow to Verify
Was there a click or impression first?Check Events API logs or dashboard
Same user ID in both events?Compare opaqueUserId or userId in click vs purchase
Within attribution window?Varies by ad format: 7 days (listings), 14 days (brands), up to 30 days (banners)
Same vendor?Purchase must be for a product from the campaign’s vendor
Event actually sent?Check for 200 response from /v2/events

​
User ID Matching

Attribution requires the same user identifier in both the ad interaction and the purchase.
ScenarioWhat to SendExample
Logged-in userYour internal user IDuserId: "user_12345"
Anonymous user (with cookie)Consistent opaque IDopaqueUserId: "abc123-session-id"
Fully anonymousNothing (no attribution possible)Cannot attribute

​
Common Mistakes

Wrong: Different IDs for same user 
// Click event
{ "opaqueUserId": "session_abc123" }

// Purchase event (same user, but different ID!)
{ "userId": "customer_456" }
These won’t match. Attribution fails silently. Correct: Consistent ID 
// Click event
{ "userId": "customer_456" }

// Purchase event
{ "userId": "customer_456" }

​
Attribution Windows

Attribution windows are configurable per ad format to match how each format influences customer behavior:
Ad FormatTypical WindowRangeWhy
Sponsored Listings7-14 days1-14 daysHigh purchase intent, shorter consideration
Sponsored Brands14-30 days7-30 daysBrand consideration period
Banner/Video Ads14-30 days14-30 daysAwareness and discovery focus
Important: A purchase outside the configured window will not attribute to the ad interaction. Need different windows? Contact support to configure custom attribution windows for your ad formats. For more on attribution concepts, see our Glossary.

​
Halo Attribution

Halo attribution credits a vendor when a user clicks on Product A but purchases Product B from the same vendor. Requirements:
  • vendorId must be included in the purchase event
  • Products must belong to the same vendor
  • Within attribution window
// Purchase event with vendorId for halo attribution
{
  "type": "purchase",
  "userId": "customer_456",
  "productId": "product_B",
  "vendorId": "vendor_123",  // Required for halo
  "items": [...]
}

​
Debugging Steps

  1. Verify events are arriving
    • Check dashboard: Events → Recent Events
    • Or query: GET /public/v1/reporting-service/interactions
  2. Check for matching user IDs
    • Export click events and purchase events
    • Compare userId or opaqueUserId fields
  3. Verify timing
    • Compare occurredAt timestamps
    • Purchase must be within window of click/impression
  4. Check vendor match
    • For halo: verify vendorId is sent with purchase
    • For direct: verify productId is in the campaign

​
Still Not Working?

If you’ve verified all the above and attribution still isn’t working:
  1. Export a sample of unattributed purchases
  2. Export clicks from the same time period
  3. Contact support with both exports and we’ll trace the specific events