Marketing Attribution & Campaign Tracking Overview
When distributing digital passes across social media ads, influencer partnerships, email newsletters, in-store QR displays, and affiliate networks, measuring channel ROI is critical. Passinstance includes native UTM Parameter Tracking (UTM Attribution Engine and UTM Tracking API at /templates/:templateId/utm-tracking) to capture traffic sources, track pass enrollment conversions, and record first-touch marketing attribution directly on every issued pass record.
Supported UTM Tags & Parameters
Passinstance standardizes the industry-standard Google Analytics UTM taxonomy alongside custom tags:
| Parameter Key | Purpose | Example Value | Best Used For |
|---|---|---|---|
utm_source | Identifies the traffic platform or referrer | facebook, instagram, newsletter, counter_qr | Determining which platform drove the visitor |
utm_medium | The marketing channel or delivery medium | cpc, social, email, print_flyer, sms | Distinguishing paid ads from organic or printed collateral |
utm_campaign | Specific promotional campaign name | spring_launch_2026, black_friday_vip, store_opening | Grouping passes issued under a specific initiative |
utm_term | Paid search keyword or audience segment | loyalty_rewards, coffee_club, fitness_sub | Tracking specific ad keywords or audience variants |
utm_content | Specific ad creative or CTA variant | blue_button, story_ad_v2, table_stand_4 | A/B testing ad variations or different counter locations |
utm_id | CRM or marketing automation campaign ID | camp_01j8k9m2, ad_99214 | Correlating pass issuance with Google Ads or HubSpot IDs |
tag | Free-form categorization identifier | store_munich, partner_nike, staff_alex | Custom tracking tags specific to your business workflow |
First-Touch Attribution Model (FIRST_TOUCH)
Passinstance implements a First-Touch Attribution Model (ATTRIBUTION_MODEL = 'FIRST_TOUCH', FIRST_TOUCH_SOURCE = 'UTM_FIRST_TOUCH'):
-
1
Session Pinning: When a prospective customer first lands on a public PassFlow (
/f/:slug) or Smart Link (/d/:slug) with UTM parameters, Passinstance writes the attribution bundle into the session storage. -
2
First-Touch Invariant: If the customer browses away, compares plans, or returns hours later via a direct link, the original campaign source that first brought them to your brand is preserved.
-
3
Immutable Pass Telemetry: Once the pass is generated, the attribution object is sealed inside the pass record in database. Subsequent pass edits or updates will never overwrite the original acquisition telemetry.
Configuring UTM Rules via Dashboard & API
Via Dashboard:
-
1
Open your template in the dashboard.
-
2
Navigate to Functionalities -> UTM & Tracking (
/templates/:templateId/utm-tracking). -
3
Toggle Enable UTM Parameter Tracking.
-
4
Set default parameters for standard template links, or define required attribution keys for partner campaigns.
Via API (UTM Tracking API):
PUT /api/v1/templates/{templateId}/utm-tracking HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json
{
"enabled": true,
"defaultSource": "direct",
"defaultMedium": "web",
"allowedTags": ["store_location", "promoter_id", "partner_code"],
"trackDeviceTelemetry": true
}
Exporting UTM Attribution in Pass Exports
All captured attribution parameters are included when exporting pass cohorts to CSV or querying passes via the REST API (POST /passes/export and GET /api/v1/passes):
Exported Telemetry Columns:
-
utm_source -
utm_medium -
utm_campaign -
utm_term -
utm_content -
utm_id -
tag -
attribution_model(FIRST_TOUCH) -
attribution_captured_at(ISO timestamp) -
attribution_captured_from(PASSFLOW,SMART_LINK, orDIRECT_API) -
attribution_landing_url -
attribution_referrer
Sample CSV Export Row:
id,serialNumber,externalId,status,utm_source,utm_medium,utm_campaign,tag,capturedAt
pass_01j9x1,PI-8821,CUST-901,ACTIVE,instagram,story,spring_launch_2026,influencer_maya,2026-03-15T14:22:10Z
URL Builder Examples for Marketing Campaigns
When distributing your public links, append UTM parameters using standard URL query syntax:
1. In-Store Table QR Code:
https://app.passinstance.com/f/coffee-club?utm_source=in_store&utm_medium=qr_code&utm_campaign=table_tents&tag=table_12
2. Instagram Story Swipe-Up Ad:
https://app.passinstance.com/f/coffee-club?utm_source=instagram&utm_medium=story_ad&utm_campaign=summer_promo_2026&utm_content=video_b
3. Email Newsletter Footer:
https://app.passinstance.com/f/coffee-club?utm_source=newsletter&utm_medium=email&utm_campaign=weekly_digest_wk11
Related Documentation
-
Self-Service Distribution — PassFlows, smart links, and NFC distribution.
-
Selling Passes — Monetizing passes via PassFlow checkout.
-
Data Exports & Reporting — Exporting pass cohorts and telemetry to CSV.
