Skip to content
Help Center Guide · Pass Distribution
3 min readVerified 2026-11-16

UTM Tracking Parameters

Track marketing campaigns, ad sources, and conversion funnels on pass distribution links and PassFlows with first-touch attribution.

In This Guide

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.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
UTM ATTRIBUTION & TELEMETRY PIPELINE
STAGE 01 MARKETING CAMPAIGN TOUCHPOINT
Customer clicks link or scans QR code containing UTM tags: https://app.passinstance.com/f/vip-club?utm_source=instagram&utm_medium=story...
STAGE 02 UTM INGESTION & ATTRIBUTION ENGINE
Ingests query tags: utm_source, utm_medium, utm_campaign, utm_term, etc
Captures HTTP Referer and initial landingUrl
Enforces First-Touch Attribution (ATTRIBUTION_MODEL = 'FIRST_TOUCH')
STAGE 03 PASS ATTRIBUTION PERSISTENCE (DATABASE)
Persisted permanently in Pass.attribution JSON field:
utm_source: "instagram"
utm_medium: "story"
utm_campaign: "summer_promo_2026"
tag: "influencer_sarah"
capturedAt: ISO Timestamp | capturedFrom: "PASSFLOW"
STAGE 04A CSV EXPORT & ANALYTICS
Included in POST/passes/export
Filter cohorts by marketing campaign
STAGE 04B INTEGRATION WEBHOOKS
Forwarded in pass.created
Sync to CRM / Google Analytics 4

Supported UTM Tags & Parameters

Passinstance standardizes the industry-standard Google Analytics UTM taxonomy alongside custom tags:

Parameter KeyPurposeExample ValueBest Used For
utm_sourceIdentifies the traffic platform or referrerfacebook, instagram, newsletter, counter_qrDetermining which platform drove the visitor
utm_mediumThe marketing channel or delivery mediumcpc, social, email, print_flyer, smsDistinguishing paid ads from organic or printed collateral
utm_campaignSpecific promotional campaign namespring_launch_2026, black_friday_vip, store_openingGrouping passes issued under a specific initiative
utm_termPaid search keyword or audience segmentloyalty_rewards, coffee_club, fitness_subTracking specific ad keywords or audience variants
utm_contentSpecific ad creative or CTA variantblue_button, story_ad_v2, table_stand_4A/B testing ad variations or different counter locations
utm_idCRM or marketing automation campaign IDcamp_01j8k9m2, ad_99214Correlating pass issuance with Google Ads or HubSpot IDs
tagFree-form categorization identifierstore_munich, partner_nike, staff_alexCustom 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. 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. 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. 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. 1
    Open your template in the dashboard.
  2. 2
    Navigate to Functionalities -> UTM & Tracking (/templates/:templateId/utm-tracking).
  3. 3
    Toggle Enable UTM Parameter Tracking.
  4. 4
    Set default parameters for standard template links, or define required attribution keys for partner campaigns.

Via API (UTM Tracking API):

HTTP
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, or DIRECT_API)
  • attribution_landing_url
  • attribution_referrer

Sample CSV Export Row:

CSV
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:

TEXT
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:

TEXT
https://app.passinstance.com/f/coffee-club?utm_source=instagram&utm_medium=story_ad&utm_campaign=summer_promo_2026&utm_content=video_b
TEXT
https://app.passinstance.com/f/coffee-club?utm_source=newsletter&utm_medium=email&utm_campaign=weekly_digest_wk11

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.