DataStated Documentation Add my site
Add my site

How attribution works

Each channel gets three plain counts on the journey panel, touched, started and closed, and the platform's own claim is drawn against them in What each platform claims. The API carries all four. None of the three is a model or a fraction of a sale, and each one traces back to the visits behind it.

The visit journey

The tag recognises a returning browser with one first-party cookie that lasts 13 months. Each visit records where it came from: the referrer, any utm_source / utm_medium / utm_campaign tags, and ad click identifiers. Nine click parameters are read to classify the channel: gclid, gbraid and wbraid map to Google Ads; gclsrc maps there only when its value is exactly aw.ds. Other non-empty gclsrc values stay unassigned to an ad platform and are excluded from Google's comparison. ttclid maps to TikTok Ads, msclkid to Bing Ads, twclid to X Ads and li_fat_id to LinkedIn Ads. These are rules applied to captured URL parameters, which can be copied or supplied by anyone. They do not independently prove that a platform served an ad. fbclid needs a paid medium, because Facebook adds it to organic outbound links too, so a bare fbclid, or a Meta utm_source with no paid medium, is plain Meta, and only an fbclid or a Meta source beside a paid utm_medium is Meta Ads. A click id wins over utm_source, which wins over the referrer. The paid mediums are cpc, ppc, paid, paid_social, paidsocial, paid-social, paid_search, paidsearch, display, retargeting and remarketing, in upper or lower case. One of them beside a platform utm_source lands in that platform's paid channel: google, adwords or youtube in Google Ads; meta, facebook, fb, instagram or ig in Meta Ads; tiktok in TikTok Ads; bing or microsoft in Bing Ads; twitter or x in X Ads; linkedin in LinkedIn Ads. Any other source with a paid medium stays as typed. From those, each visit lands in a channel: Google Ads, Meta Ads, TikTok Ads, Bing Ads, X Ads or LinkedIn Ads for traffic classified as paid; Google, Facebook, TikTok, Bing and the other search engines and social networks by name for an organic referral; whatever utm_source says; the referring site; or direct.

Sessions, new visitors, bounces

A session is one visitor's run of events with no gap longer than 30 minutes. The server numbers each visitor's sessions as they happen and stamps every pageview with that number, so new and returning are read from the record rather than guessed: a visitor with a pageview from their first session in the range is new, and one whose pageviews in the range all come from later sessions is returning. A visitor whose rows carry no number (recorded before this existed) is in neither bucket, so the two add up to the visitor count only once every row has one.

Visit time is the visible time the tag reported per page, summed over the session. A session is measured when at least one of its pageviews carried a value; unmeasured sessions are left out of both figures instead of counting as zero. A bounce is a measured session that saw one page for under 10 seconds, and bounce rate is bounces over measured sessions.

Standing credit

Every visit updates the visitor's standing credit: the most recent non-direct channel that brought them in. When a conversion happens, whether an order from Stripe or Shopify or a goal from the tag, it inherits that standing credit at the moment it is written, and the credit never changes afterwards, except that a better Stripe or Shopify match can move the order to its real visitor. A buyer who clicked a Meta ad on Tuesday and typed your URL on Thursday still credits Meta Ads, because "typed it in" is not a marketing channel.

The four measures

For each channel, the journey panel shows three separate counts, side by side, and the platform's claim is drawn against them in What each platform claims:

  • Claimed: what the ad platform itself reports for the period, when a platform connection is configured. It lives in What each platform claims and in the API's journey rows, not on the journey panel. A channel with no claim data shows exactly that, never a fabricated zero: absence of testimony is not a count.
  • Touched: how many of the period's sales this channel appears in, anywhere in the buyer's journey before the order.
  • Starts the sale: sales whose buyer's very first recorded visit came through this channel.
  • Closes the sale: sales stamped with this channel as the standing credit described above.

The four numbers answer different questions, so none is folded into another: three on the journey panel, the claim beside them in What each platform claims, all four in the API. There is no attribution-model toggle.

The gap

With an ad platform connected, its reported conversion count appears beside processor-confirmed orders attributed to its paid channel. The comparison is per platform. Campaign rows contain the platform's own reported results; they are not reconciled to individual orders. Different attribution rules and missing tracking can both create a gap.

Known USD ad records support spend totals, claimed revenue, CPC and platform-reported ROAS. Revenue gaps and efficiency figures also require processor-confirmed payments with compatible USD currency. Unknown, mixed or non-USD currency makes the combined dollar comparison unavailable; currency groups remain separate, with no exchange-rate conversion. Re-sync older ad records that lack account currency. Self-reported orders stay separate from confirmed payments, and a revenue gap does not measure sales caused by an ad.

A platform's claim is compared only against orders on its own paid channel: Google Ads against Google Ads orders, TikTok against TikTok Ads orders, and Meta against Meta Ads orders only. A bare fbclid or utm_source=meta without a paid medium stays outside Meta's comparison. Organic and unassigned channels are excluded. The source migration applies these rules to stored history too; it does not turn a captured parameter into independent evidence of an ad click.

What makes revenue verified

Stripe checks payment status against the processor's records. The Shopify app reads store order and payment records; its guide describes the coverage. Orders sent by the browser or your events API are self-reported. Deduplicating an id prevents repeat counting; it does not confirm payment.

The claims API separates verifiedRevenue backed by Stripe or reconciled Shopify payments from unverifiedRevenue. Other analytics totals include recorded orders from either source. Check provenance and currency scope. Attribution still depends on captured links and a visitor match, so even a confirmed payment does not prove an ad caused it.

Questions? Email us at hello@datastated.com.