Marketing Attribution System

Track which channels and campaigns drive revenue. Set up attribution rules for UTM, order tags, and product-based matching in MerchantFlow.

Marketing Attribution System

Feature flag: Everything on this page is gated behind the attribution_enabled feature flag, which is off unless MerchantFlow turns it on for your workspace -- it resolves to off when the flag row is missing, when it is disabled, when your workspace is not on its allowlist, and whenever the lookup fails. There is no plan tier and no self-serve toggle that unlocks it.

With the flag off:

The Marketing → Attribution navigation entry is hidden, and /dashboard/attribution renders a locked panel reading "Advanced attribution is not currently enabled for your account. Contact support if you'd like to enable multi-touch attribution analysis."

The Revenue Attribution card disappears from your main dashboard, from Marketing → Traffic, and from the product detail page (along with that page's Attribution Breakdown card)

Blended cost mode is forced on, so daily ad spend is spread across every order rather than only paid-attributed ones

The MCP tool run_sales_by_channel_report refuses with "Per-channel attribution is disabled for this tenant"

Contact [email protected] if you want it turned on for your workspace. The Traffic page at /dashboard/traffic is separately gated behind search_console_enabled.

Interface maturity: the on-page projects/channels/rules interface is currently a read-only viewer with a one-click initializer. Creating and editing projects, channels, and rules is done through the API, not the dashboard. The multi-touch attribution models described further down are fully live and drive the numbers you see across the dashboard.

The MerchantFlow attribution system connects revenue and expenses to the marketing channels, campaigns, and projects that generated them. By setting up attribution rules, you can calculate the true ROI of every marketing initiative and make data-driven budget allocation decisions.

What Is Marketing Attribution?

Marketing attribution is the process of assigning credit for revenue and expenses to their sources:

Which projects generated revenue?
Which marketing channels drove sales?
What is the ROI of each campaign?
Which initiatives are profitable?

Why Attribution Matters

Without attribution:

You know total revenue but not which campaigns worked
Cannot calculate ROI for specific marketing channels
Cannot identify which projects are profitable
Cannot make data-driven marketing budget decisions

With attribution:

See revenue broken down by marketing channel
Calculate ROI for each project and campaign
Identify highest-performing campaigns
Allocate budget to the best-performing channels

How to Access the Attribution Dashboard

Navigate to Marketing > Attribution (/dashboard/attribution). The page is titled Attribution System, subtitled "Manage projects, channels, and attribution rules".

It has three tabs:

Projects -- the projects on your workspace
Channels -- the channels on your workspace
Rules -- the rules that assign orders to them. The card inside this tab is headed Attribution Rules, and each rule shows its Priority, its type, its description, its raw conditions, and an Active or Inactive badge

Each tab lists what exists. Empty tabs show "No projects found", "No channels found", or "No rules found". There are no create, edit, delete, or drag-to-reorder controls on this page.

Model comparison does have a dashboard surface, just not on this page: the Revenue Attribution card on your main dashboard has a Detailed Analytics button that opens the Revenue Attribution Overview modal, which reads /api/attribution/compare. Unattributed-revenue breakdowns and customer-journey paths exist only as API endpoints (/api/attribution/unattributed, /api/attribution/paths) and have no dashboard page at all.

Attribution Components

What Are Projects?

Projects are business initiatives or campaigns you want to track:

Product launches
Seasonal campaigns (e.g., "Holiday 2025 Campaign")
Market expansion initiatives
Website redesigns
Influencer partnerships
Content marketing initiatives

A project record carries a name, a description, and a status (active or completed). Revenue and expense roll-ups per project are served by the reporting API rather than shown on the attribution page.

What Are Channels?

Channels are marketing traffic sources:

Google Search (organic)
Google Ads (paid search)
Facebook/Instagram Ads
Email marketing
Affiliate marketing
Influencer partnerships
Organic social, direct traffic, and referral traffic

A channel record carries a name, a type (organic, paid, direct, social, email, or referral), and a description. These configured channels are separate from the eleven channel groups the attribution engine derives from touchpoint source and medium, listed further down.

What Are Attribution Rules?

Attribution rules assign revenue to projects and channels based on order data. A rule has a type (revenue, expense, or both), a priority, a set of conditions, and the project and channel to assign.

Revenue rules are matched against exactly three fields on the order:

source -- the order's utm_source, falling back to the platform's primary source
medium -- the order's utm_medium
campaign -- the order's utm_campaign

Expense rules are matched against category, vendor, and type on the expense.

Within one rule, every condition you list must match -- conditions are combined with AND. A condition value can be a single string (case-insensitive exact match), an array (matches if any entry matches, so OR within that one field), or { "$contains": "..." } for a substring match. There is no order-tag, product, or date-range matching: a condition on any field outside the lists above can never match.

How to Set Up Attribution

Initialize the System

Go to Marketing > Attribution
Click "Initialize Attribution System"
MerchantFlow creates a default General project ("Default project for unmatched items") and six channels:

Channel	Type
Organic Search	organic
Paid Search	paid
Direct	direct
Social	social
Email	email
Referral	referral

It also seeds three default rules:

Priority	Type	Conditions	Assigned to
100	revenue	source `google`, medium `cpc`	General / Paid Search
90	revenue	source `google`, medium `organic`	General / Organic Search
80	expense	category `advertising`	General / Paid Search

Initialization is instant. It does not scan your order history, detect channels from your data, or suggest projects - it seeds a fixed default set. The button disappears once at least one project exists, and re-running it returns an "already initialized" error.

Adding Your Own Projects, Channels, and Rules

There is no interface for this yet. Projects, channels, and rules are created through the API (POST /api/attribution/projects, /api/attribution/channels, /api/attribution/rules), and orders or expenses can be reassigned through /api/attribution/reassign.

If you need a campaign-specific project or a custom channel set up, contact [email protected].

What Rules Can Express

The rule engine matches on source, medium, and campaign for revenue, and on category, vendor, and type for expenses, with a priority order deciding which rule wins when several match. Because there is no rule editor in the dashboard, treat this section as a description of what the engine can do rather than a set of steps you can follow today.

How to Read Attribution Reports

Project Performance

The Projects tab lists each project with its name, description, and status (active or completed). Revenue, expense, and ROI reporting per project is served by /api/attribution/project-report and is not rendered on this page.

Channel Performance

The Channels tab lists each channel with its name, type, and description.

ROAS benchmarks, for when you are reading channel returns elsewhere in the dashboard:

3x: Minimum viable
4-5x: Good
6x+: Excellent

Unattributed Revenue

An /api/attribution/unattributed endpoint reports orders with no attribution, but there is no Unattributed page in the dashboard. The goal is still to keep unattributed revenue below 10%.

Common causes of unattributed revenue:

Missing UTM parameters on campaign links
Direct traffic without tracking
Returning customers from earlier campaigns
Missing attribution rules

How Ad Spend Is Attributed

If Google Ads, Meta Ads, TikTok Ads, or Snapchat Ads are connected, ad spend syncs automatically and is allocated to orders, which is what feeds the ad spend figures on Discount Codes, Customer LTV, and per-order profitability.

Manually entered expenses cannot be tagged to a project or channel by hand - the expense form has no project or channel field. They are still attributed automatically: every expense you save is run through the expense rules on its category, vendor, and type, and anything that matches no rule falls to the default project and channel. The seeded rule set sends advertising expenses to General / Paid Search.

How to Calculate ROI and ROAS

Project ROI

Project-level ROI is served by the reporting API and has no dashboard view, so treat the formula below as the standard definition rather than a number you can currently read off a MerchantFlow page:

ROI = ((Revenue - Expenses) / Expenses) x 100

Example: Project revenue $50,000 with $10,000 expenses = 400% ROI ($4 for every $1 spent).

ROI benchmarks: 100%+ profitable, 200%+ good, 400%+ excellent, 1000%+ outstanding.

Channel ROAS Formula

ROAS = Revenue / Ad Spend

Example: Channel revenue $30,000 with $6,000 ad spend = 5.0x ROAS.

ROAS vs. ROI: Use ROAS for channel comparison and ad optimization. Use ROI for overall project profitability including all costs.

Best Practices for Attribution

1. Use Consistent UTM Parameters

Standardize UTM naming conventions (e.g., always use "facebook" not "Facebook" or "FB"). Document standards and share with your team.

2. Tag Campaigns Before You Launch Them

Get UTM parameters onto every campaign link before it goes live. Touchpoints are rebuilt at sync time from what your platform recorded on the order -- for Shopify, the first and last visit in its customer journey summary. A visit your store did not tag cannot be tagged retroactively, so an untagged campaign is untagged forever.

3. Record All Marketing Expenses

Log contractor fees, creative production, influencer payments, and content costs as expenses so they reach your P&L, even though they cannot currently be tagged to a project.

4. Review Unattributed Revenue Weekly

Check unattributed revenue weekly, identify missing rules, and aim for less than 10% unattributed.

5. Compare Models Before Trusting One

Last Touch flatters the bottom of the funnel and First Touch flatters the top. A channel that looks strong under every model is genuinely strong; one that only looks good under a single model deserves scrutiny.

6. Use Attribution for Budget Decisions

Let attribution data guide budget allocation: increase spend on high-ROAS channels, pause low-ROI projects, and replicate successful strategies.

Advanced Attribution Features

Attribution Models

MerchantFlow computes all five attribution models for every order at sync time, so switching models never requires a recalculation.

Model	Key	How Credit Is Assigned
First Touch	`firstTouch`	100% credit to the first touchpoint in the customer journey
Last Touch	`lastTouch`	100% credit to the last touchpoint before purchase
Linear	`linear`	Equal credit split across all touchpoints
Time Decay	`timeDecay`	Exponential decay measured back from the most recent touchpoint, using a 7-day half-life: a touchpoint 7 days before the last one carries half its weight. With a single touchpoint it collapses to first-touch
Position-Based	`positionBased`	40% first, 40% last, 20% shared among the middle touchpoints. With exactly two touchpoints it becomes a 50/50 split, and with one touchpoint it collapses to first-touch

The default model is Last Touch, and the default attribution window is 30 days, both stored per workspace and readable through /api/attribution/settings. An order with no touchpoints at all is credited 100% to direct / (none) in the Direct channel group under every model.

An Attribution Settings page exists at /dashboard/settings/attribution with a Default Attribution Model radio group covering all five models, an Attribution Window dropdown offering 7, 14, 30, 60, and 90 days, and a Blended Cost Mode toggle. It is not linked from the Settings tab bar, so you reach it by URL.

Model comparison has a dashboard surface through the Detailed Analytics button on the Revenue Attribution card. The modal it opens, Revenue Attribution Overview, has a five-model selector across the top; switching models refreshes the Confidence score, which is derived from how much revenue the selected model leaves unattributed. The channel rows beneath it come from the seven-bucket traffic split described on Traffic Sources, not from the selected model.

Channel Groups

Touchpoints are classified into channel groups from their source and medium, in this order:

Channel group	Matched when
Paid Social	A social source with a paid medium
Organic Social	A social source with any other medium
Paid Search	A paid medium on a non-social source
Organic Search	Medium is `organic`
Email	Medium is `email`
Referral	Medium is `referral`
Direct	Source is `direct` or `(direct)`, or medium is `(none)`
Display	Medium contains `display` or `banner`
Affiliate	Medium is `affiliate`
Shopping	Source contains `shopping`, or medium is exactly `shopping`
Other	Anything else

A social source is one whose name contains facebook, instagram, meta, tiktok, snapchat, linkedin, twitter, or pinterest. A paid medium is exactly one of cpc, ppc, paid, paidsocial, paid_social, cpv, or cpm -- or any medium that merely contains the word paid.

Social sources are checked before the generic paid check, so facebook / cpc correctly lands in Paid Social rather than Paid Search. Direct is checked before Display, Affiliate, and Shopping, so a touchpoint whose medium is (none) becomes Direct no matter what its source says.

The attribution report does not use a single classifier. Which one an order goes through depends on the confidence tier it lands in:

Orders with a stored attribution record (High confidence) keep the channel group written onto their touchpoints at sync time -- the eleven groups in the table above, including Paid Social, Organic Social, and Organic Search.
Orders that fall back to their UTM fields or platform source (Medium confidence) are classified on the fly by a second, coarser scheme that has no paid/organic split: it emits Organic, Shopping, Paid Search, Social, Email, Referral, ChatGPT, Direct, and Other.
Orders with nothing usable land in a row of their own, Unattributed.

Grouped by channel, one report can therefore list Paid Social and Social as separate rows, and Organic Search alongside Organic, because they came from different tiers of the same table. They are not double-counted -- each order contributes to exactly one row -- but the rows are not directly comparable. The coarser scheme is also stricter about search: it only recognises the literal source google for Organic, Paid Search, and Shopping, so bing / cpc on a Medium-confidence order lands in Other.

Sync writes an attribution record for every order it processes, so most of your revenue sits in the High-confidence tier and shows the eleven groups. The coarser rows turn up for orders whose attribution enrichment has not run yet -- enrichment is non-fatal and retried on the next sync -- so a mixed table usually means a recent sync left some orders behind rather than that anything is broken.

Cross-Device Attribution

Currently relies on user authentication or UTM parameters. Enhanced cross-device tracking with better user identity resolution is planned.

Troubleshooting Attribution

Revenue Not Attributing

Verify that the attribution system has been initialized, that orders carry a usable utm_source or platform source, and that touchpoints are being recorded. An order with no touchpoints is always credited to Direct.

Wrong Project or Channel Attribution

Rule priority decides which rule wins. Because rules cannot be edited from the dashboard, contact support with the order and the expected assignment.

ROI Seems Wrong

Verify all expenses are attributed to the project, revenue is correctly attributed, the date range includes all relevant data, and there is no double-counting of expenses.

Expenses Not Showing in a Project

You cannot choose the project yourself - the expense form has no project field. Expenses are assigned automatically by the expense rules, and with no matching rule they go to the default project rather than the one you expected. Because there is no project roll-up view in the dashboard, the assignment is only visible through /api/attribution/project-report.

Expense Tracking -- track and attribute expenses
Ads and Channels -- campaign-level ad performance
Bank Balance -- connect attribution to cash planning
P&L Overview -- complete financial picture
Dashboard Overview -- navigate MerchantFlow

Last updated: August 29, 2026

Marketing Attribution System

On this page