Purchase Referral Attribution

You may be interested in analyzing the referral sources to your storefront for purchases. This information is included alongside Purchase information in the referral object, if it is available.

• referral.source is derived from a combination of UTM parameters, click IDs, and HTTP headers sent in the initial request.
• referral.method describes which method was used for deriving the referral.source.
• referral.host provides the host of the HTTP referer header, if it was passed in.
• referral.utmMedium provides the raw value of the utm_medium query parameter, if it was passed in.
• referral.utmCampaign provides the raw value of the utm_campaign query parameter, if it was passed in.
• referral.utmSource provides the raw value of the utm_source query parameter, if it was passed in.

(recommended) Add utm_source to links to your webshop

Ensure any direct links to your storefront URL have the utm_source query parameter appended.

Some sites, like Facebook, automatically append click ID's, UTM parameters, or send the referer header to their URLs to allow attribution to work. Others, like Discord, do not do this. If you want to track referrals consistently, we recommend appending theutm_source param to all of your respective URLs accordingly:

www.exampleshop.com/?utm_source=discord

utm_source values are typically lowercase with no spaces. Neon recognizes the following: facebook, discord, instagram (mapped to facebook), twitter, youtube, google, chatgpt, support, tiktok, email, linktree. These are normalized into a curated source value returned in the purchase.completed webhook and the GET /purchases API.

source is resolved in priority order: a matched utm_source, then a known click ID (fbclid, gclid, …), then the referring domain - falling back to null if none match. method reflects which of those matched (utm, click_id, or referer), or null if none did. host holds the referring domain when method is referer, and null otherwise.

utmSource always reflects the raw utm_source query parameter exactly as received, regardless of whether it matched a curated source. Values over 255 characters or empty strings are dropped to null.

Ingest the purchase data via webhook or API

To read the referral object on the Purchase, you can ingest the purchase.completed webhook or call the Purchase API (e.g. GET /purchases ).

The referral object on a purchase looks like this:

"referral": {
  "method": "utm",
  "host": null,
  "source": null, 
  "utmMedium": "paid_social",
  "utmCampaign": "summer_sale",
  "utmSource": "some_custom_source" // always comes from 'utm_source' url parameter
}

(optional) Add utm_medium and utm_campaign for more granular tracking

In addition to utm_source, you can append utm_medium and utm_campaign query parameters to your storefront links for more detailed campaign attribution:

www.exampleshop.com/?utm_source=discord&utm_medium=social&utm_campaign=summer_sale

These two aren't mapped to a fixed set of values - whatever you pass through is returned as-is in referral.utmMedium and referral.utmCampaign on the Purchase object.