docs: clarify override key conflict resolution

Author: lordhumunguz

data-inputs/platform-supporting-resources/shopify/backfilling-utm-attribution-via-checkout-attributes.mdx

@@ -45,7 +45,7 @@ To reduce collisions with other checkout apps, prefer the `sm_utm_*` / `sm_utmPa
 | `sm_utm_source`, `sm_utm_medium`, `sm_utm_campaign`, `sm_utm_content`, `sm_utm_term`, `sm_utm_id` | SourceMedium override UTMs (recommended) | `sm_utm_source=facebook` |
 | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `utm_id` | Standard UTMs | `utm_campaign=summer_sale_2025` |
 | `sm_utmParams`, `utmParams`, `GE_utmParams` | Aggregate UTM query string (parsed) | `utm_source=google&utm_medium=cpc` |
-| `referrer` | Referring URL | `https://blog.example.com/review` |
+| `sm_referrer`, `referrer` | Referring URL | `https://blog.example.com/review` |
 
 ### Click IDs (fallback inference)
 
@@ -62,6 +62,16 @@ Click IDs are processed but **not stored as raw values**. If no explicit `utm_so
 
 If multiple click IDs exist, the system prioritizes: `scclid` > `irclickid` > `msclkid` > `ttclid` > `fbclid` > `gclid`.
 
+### Conflict resolution (deterministic)
+
+If you provide conflicting values (e.g., both `sm_utm_source` and `utm_source`, or both direct keys and `utmParams`), SourceMedium resolves each final field with a deterministic waterfall:
+
+- **UTM fields**: direct `sm_utm_*` → direct `utm_*` → parsed from `sm_utmParams` → parsed from `utmParams` → parsed from `GE_utmParams`
+- **`utm_source` only**: if still missing, infer from click IDs (`scclid` → `irclickid` → `msclkid` → `ttclid` → `fbclid` → `gclid`)
+- **Referrer**: `sm_referrer` → `referrer`
+
+If the same normalized key appears multiple times at the same level (e.g., `utm_source` and `UTM_SOURCE`), SourceMedium de-dupes deterministically using `MAX()` (lexicographically largest value). To avoid surprises, only set each key once.
+
 ---
 
 ## Backfilling Historical Orders
@@ -400,7 +410,7 @@ const attributes = {
   ttclid: getParam('ttclid'),
   fbclid: getParam('fbclid'),
   gclid: getParam('gclid'),
-  referrer: document.referrer || null,
+  sm_referrer: document.referrer || null,
 };
 
 const cleanAttributes = Object.fromEntries(

data-transformations/attribution-source-hierarchy.mdx

@@ -81,7 +81,30 @@ Keys are **normalized** (case + delimiter + snake/camel agnostic) before matchin
 | `sm_utm_source`, `sm_utm_medium`, `sm_utm_campaign`, `sm_utm_content`, `sm_utm_term`, `sm_utm_id` | SourceMedium override keys (recommended to avoid collisions with other apps) |
 | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `utm_id` | Standard UTM keys |
 | `sm_utmParams`, `utmParams`, `GE_utmParams` | Aggregate UTM query-string fields (parsed into individual UTM keys) |
-| `referrer` | Referring URL |
+| `sm_referrer`, `referrer` | Referring URL |
+
+### Conflict resolution (deterministic)
+
+If your `customAttributes` data is messy (duplicate keys, multiple sources provided), SourceMedium applies a deterministic waterfall to resolve each final field.
+
+#### Field-level precedence
+
+For each UTM field, the **first non-empty value wins** (highest → lowest):
+
+1. Direct SM override key (`sm_utm_*`)
+2. Direct standard UTM key (`utm_*`)
+3. Parsed from `sm_utmParams` (query string)
+4. Parsed from `utmParams` (query string)
+5. Parsed from `GE_utmParams` (query string)
+6. **`utm_source` only**: click ID inference (`scclid` → `irclickid` → `msclkid` → `ttclid` → `fbclid` → `gclid`)
+
+`referrer` is resolved similarly: `sm_referrer` → `referrer`.
+
+#### Duplicate keys (same tier)
+
+If the same normalized key appears multiple times at the same tier (for example both `utm_source` and `UTM_SOURCE`, or repeated `utm_source` entries), SourceMedium de-dupes deterministically using `MAX()` (lexicographically largest value after decoding/cleaning).
+
+To avoid surprises, only set each key once.
 
 <Note>
 Click IDs are processed as a **fallback** (see below), but the raw click ID values are not stored as attribution fields.
@@ -106,6 +129,11 @@ When only a click ID is present (no explicit `utm_source`), the system infers a
 
 If an order has multiple click IDs, the highest-priority click ID wins. This preserves more specific intent signals (like affiliates or smaller platforms) over ambient IDs from high-volume platforms.
 
+Click IDs are checked in this order:
+1. Direct `customAttributes` click ID keys (e.g., `scclid`, `gclid`)
+2. Click IDs embedded inside `utmParams`
+3. Click IDs embedded inside `GE_utmParams`
+
 <Note>
 Click IDs are **fallback only**. If an explicit `utm_source` exists, it takes precedence over any click ID inference.
 </Note>