# Analytics
Source: https://docs.linkutm.com/analytics/overview

What's tracked, what's surfaced, and how retention works.

Every click on a linkutm short link is logged with details about where the visitor came from, what device they used, and their location. The Analytics page shows this as charts and tables at the workspace level and per individual link.

## What's tracked per click

| What you see              | Notes                                       |
| ------------------------- | ------------------------------------------- |
| **Time**                  | When the click happened                     |
| **Country, region, city** | Based on the visitor's location             |
| **Device**                | Mobile, tablet, or desktop                  |
| **Browser & OS**          | Chrome, Safari, iOS, Android, etc.          |
| **Referrer**              | The site or app that sent them to your link |

## When to use it

* Check workspace-level performance to see which channels are driving the most traffic.
* Open a specific link to debug whether it's working or compare two creative variants.
* Share the workspace analytics view with stakeholders for a channel performance overview.
* Export link data as CSV for client reports or offline analysis (Links → Export).

Pair with a product analytics tool (GA4, Mixpanel, Amplitude) for funnel and conversion data. linkutm shows clicks. Your other tools show what happened after.

## What the Analytics page shows

<Tabs>
  <Tab title="Workspace view">
    * **Total clicks** in the date window.
    * **Unique visitors**.
    * **Top links** by click count.
    * **Clicks over time**: daily chart.
    * **Top countries**: bar and map view.
    * **Top sources**: by `utm_source` of the originating link.

    <Frame>
      <img alt="Workspace Analytics - Total Clicks, Unique Visitors, Countries, conversion rate, Clicks Over Time bar chart, Traffic Sources, Top Links, and Geographic Distribution" />
    </Frame>
  </Tab>

  <Tab title="Per-link view">
    * **Total clicks** and **unique visitors**.
    * **Clicks over time**: daily chart.
    * **Top countries, regions, cities**.
    * **Top referrers**.
    * **Device, browser, and OS breakdown**.

    <Frame>
      <img alt="Per-link analytics - Total Clicks, Unique Users, Referrers, Devices counters, and Link Activity line chart" />
    </Frame>

    <Frame>
      <img alt="Per-link analytics - Browsers table, Referrers, UTM Tags panel, and OS breakdown" />
    </Frame>

    <Frame>
      <img alt="Per-link analytics - OS table and Devices donut chart showing Mobile, Desktop, and Tablet split" />
    </Frame>

    <Frame>
      <img alt="Per-link analytics Countries - world map with US hovered showing visit count tooltip, country table below" />
    </Frame>
  </Tab>
</Tabs>

## Real-world example

After a Q2 launch:

```
Workspace analytics, last 30 days:
- 18,420 clicks across 24 links
- 11,238 unique visitors
- Top source: google (cpc) - 8.3k clicks
- Top country: US - 12.1k
- Top device: mobile - 11.2k

Per-link: q2-launch-google
- 8,302 clicks
- 73% mobile, 24% desktop, 3% tablet
- Top referrer: Direct (typed/QR/in-app browser)
- Top country: US 71%, UK 9%, CA 6%
```

This tells the marketer: Google Ads drove most volume, mostly mobile, mostly US. Optimize the landing page for mobile US and consider expanding the UK budget.

<Frame>
  <img alt="Analytics date range picker - preset options (Last 7 days, Last 30 days, etc.) and dual-month calendar for custom ranges" />
</Frame>

## Common mistakes

<AccordionGroup>
  <Accordion title="Treating clicks as conversions">
    A click is not a sale, signup, or page view. Pair with GA4 or Mixpanel using the UTMs attached to your links for downstream events.
  </Accordion>

  <Accordion title="Counting bot traffic as real visits">
    Platforms like Slack and WhatsApp automatically fetch link previews when someone pastes a URL. These preview fetches are filtered out and not counted as clicks.
  </Accordion>

  <Accordion title="Querying beyond the retention window">
    Each workspace has a data retention window. Queries for older data are automatically cut off at the start of the window.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Retention window.** Queries are capped to your plan's retention window. Data older than the window is not returned.
</Note>


# Chrome extension
Source: https://docs.linkutm.com/getting-started/chrome-extension

Build and shorten links directly from your browser without opening the dashboard.

The linkutm Chrome extension lets you create UTM-tagged short links from any tab in your browser. Your workspace, templates, and saved parameters are all available inside the extension. No need to switch to the dashboard while you work.

<Frame>
  <img alt="linkutm Chrome extension - link creation panel showing destination URL, UTM fields, and short link output" />
</Frame>

## When to use it

* Building links on the fly while browsing a page you want to promote.
* Shortening and tagging URLs quickly without leaving your current tab.
* Using your saved templates and UTM parameters without opening linkutm in a separate window.

## How to install it

<Steps>
  <Step title="Open the extension page">
    In the linkutm sidebar, click the puzzle-piece icon at the bottom. This opens the Chrome Web Store listing.
  </Step>

  <Step title="Add to Chrome">
    On the Chrome Web Store page, click **Add to Chrome** and confirm the prompt.
  </Step>

  <Step title="Connect your account">
    Click the linkutm icon in your Chrome toolbar. The extension will prompt you to log in. Sign in with your existing linkutm account. The extension connects automatically.
  </Step>

  <Step title="Pin the extension (optional)">
    Click the puzzle-piece icon in Chrome's toolbar, find linkutm, and click the pin icon so it stays visible.
  </Step>
</Steps>

## Real-world example

You're on a product page you want to run a LinkedIn campaign to. Instead of copying the URL, switching tabs, and creating a link in the dashboard:

1. Click the linkutm icon in your toolbar.
2. The destination URL is pre-filled.
3. Pick a template or fill UTM fields.
4. Hit **Create**. Your short link is copied to your clipboard.

## Common mistakes

<AccordionGroup>
  <Accordion title="Extension not connecting after install">
    Make sure the extension is enabled in Chrome. Go to the extensions menu and check that the linkutm toggle is on. Then click the icon and sign in again.
  </Accordion>

  <Accordion title="Links not appearing in the right workspace">
    You can switch workspaces directly in the extension. Use the workspace switcher inside the extension to select the correct workspace.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Chrome and Chromium only.** The extension works in Google Chrome and Chromium-based browsers (Edge, Brave). It is not available for Firefox or Safari.
</Note>

<Note>
  **Staying logged in.** The extension stays connected as long as your linkutm session is active. If you log out of linkutm, you will need to reconnect the extension.
</Note>


# Quickstart
Source: https://docs.linkutm.com/getting-started/introduction

Sign up, create a workspace, ship your first tracked link in under 3 minutes.

<Note>
  **Stack at a glance.** linkutm = workspace + links + UTMs + analytics. Everything is scoped to a workspace. Run multiple workspaces (e.g., one per client) and switch between them from the workspace picker.
</Note>

## 1. Create an account

<Steps>
  <Step title="Sign up">
    Go to [app.linkutm.com](https://app.linkutm.com) and sign in with email/password or Google. Verify your email if prompted.
  </Step>

  <Step title="Name your workspace">
    During onboarding you pick a workspace name (your company or client) and a slug. The slug becomes part of your URL: `app.linkutm.com/{slug}/links`.

    <Tip>Slug must be lowercase letters, numbers, hyphens. It's checked for availability live.</Tip>
  </Step>

  <Step title="Done">
    You land in the workspace with a default short domain attached. Add a [custom domain](/link-shortening/custom-domains) later for branded links.
  </Step>
</Steps>

<Tip>
  **Setting this up for a team or agency?** Agree on your [UTM naming convention](/playbooks/utm-naming-convention) and configure UTM Rules *before* inviting anyone. Rules apply to all new links going forward. Enforcing consistency after 50 links already exist is much harder.
</Tip>

## 2. Create your first link

<Steps>
  <Step title="Open the link builder">
    From the sidebar: **Links → Create Link** (or press the **+** button).
  </Step>

  <Step title="Paste destination URL">
    Full URL with `https://`. Example: `https://example.com/pricing`.
  </Step>

  <Step title="Fill UTMs">
    The five standard fields:

    | Field          | Example         | Required      |
    | -------------- | --------------- | ------------- |
    | `utm_source`   | `google`        | typically yes |
    | `utm_medium`   | `cpc`           | typically yes |
    | `utm_campaign` | `q2-launch`     | typically yes |
    | `utm_term`     | `running-shoes` | optional      |
    | `utm_content`  | `headline-a`    | optional      |

    <Tip>Apply a [template](/utm-templates/overview) instead of typing - saves time and prevents typos.</Tip>
  </Step>

  <Step title="(Optional) custom slug">
    Leave blank for auto-generated short code. Type your own for branded slugs like `q2-launch`.
  </Step>

  <Step title="Create">
    Click **Create**. The link is live immediately.
  </Step>
</Steps>

<Frame>
  <img alt="Create Link modal - Destination URL, Short Link, Title, Tags, Folder, UTM parameters tab, QR preview, and link preview card" />
</Frame>

## 3. Test the redirect

Open the short link in a private window. You'll be redirected to your destination URL with all UTMs appended:

```
https://yourshort.link/q2-launch
↓
https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=q2-launch
```

<Frame>
  <img alt="Links dashboard - list view showing Link title, short URL, destination, tags, click count, and created date" />
</Frame>

The click is recorded. Open the link's analytics tab - country, device, browser, referrer all populate within seconds.

## 4. Next steps

<CardGroup>
  <Card title="Set UTM standards" icon="gavel" href="/playbooks/utm-naming-convention">
    Approved source, medium, and campaign values - the convention your team follows.
  </Card>

  <Card title="Save a template" icon="copy" href="/utm-templates/create-template">
    Lock in source/medium for a channel so the team can't drift.
  </Card>

  <Card title="Add a custom domain" icon="globe" href="/link-shortening/custom-domains">
    `go.yourbrand.com/q2-launch` instead of the default.
  </Card>

  <Card title="Invite teammates" icon="user-plus" href="/team-collaboration/overview">
    Roles, permissions, notification preferences.
  </Card>
</CardGroup>

## How linkutm thinks about your data

<AccordionGroup>
  <Accordion title="Workspaces are the unit of isolation">
    Links, folders, tags, templates, UTM rules, custom domains, pixels, API keys, analytics - all scoped per workspace. A user in one workspace cannot access the links, analytics, or settings of any other workspace. Useful for agency-style multi-client setups.
  </Accordion>

  <Accordion title="Short codes are globally unique">
    Even though links are workspace-scoped, the short code (the part after `yourshort.link/`) is unique across the system. If you try to use a slug another workspace already grabbed, creation fails with a conflict error.
  </Accordion>

  <Accordion title="UTMs run through workspace rules">
    Before a link saves, your workspace's UTM Rules are applied: lowercase, space replacement, max length, prohibited terms. The cleaned values are what gets stored. See [UTM Rules](/utm-rules/overview).
  </Accordion>

  <Accordion title="Analytics has a retention window">
    Each workspace has a retention window for click data. Queries beyond that window are clipped to it.
  </Accordion>
</AccordionGroup>


# Common issues
Source: https://docs.linkutm.com/help/common-issues

Quick fixes for the things that break most often.

<AccordionGroup>
  <Accordion title="My short link isn't working">
    Possible causes:

    * **Slug typo.** Compare what you typed vs the saved short code in linkutm.
    * **Wrong domain.** You might be visiting the link on a different domain than it was created on. Check the full short URL on the link detail page.
    * **Reserved path.** A small set of paths are reserved by the system (`api`, `health`, `docs`). If your slug matches one of these, rename it.
  </Accordion>

  <Accordion title="My short link says it's expired">
    The link has passed its expiration date. If a fallback URL is set, visitors are sent there instead. Edit the link and extend or clear the expiry date to restore the original destination.
  </Accordion>

  <Accordion title="Custom domain stuck on 'pending'">
    * **CNAME not pointing.** Confirm your CNAME record matches the target shown
      in linkutm. - **Cloudflare proxied.** Set the
      record to **DNS only** (gray cloud), not proxied. - **DNS propagation lag.**
      Wait 5-30 min after changing DNS, then click **Verify** again. - **TTL too
      high.** Drop TTL to 300 before re-verifying.
  </Accordion>

  <Accordion title="UTM values get changed on save">
    Workspace UTM Rules are running. Default behavior:

    * **Force lowercase** lowercases everything automatically.
    * **Space character** replaces spaces with `_` (or your configured character).

    Open the saved link to see the final stored values. To change this behavior, go to [UTM Rules](/utm-rules/overview).
  </Accordion>

  <Accordion title="Validation error: 'Value contains prohibited term'">
    A workspace UTM rule has a banned substring (e.g., `test`, `draft`). Either
    rename the value or remove the prohibited term from rules.
  </Accordion>

  <Accordion title="Error: 'Link limit reached'">
    Your workspace is at its maximum link count. Delete or archive unused links
    to free up space. The workspace owner gets a warning email when approaching the limit.
  </Accordion>

  <Accordion title="Error: 'Domain or Template limit reached'">
    Each resource type has its own maximum per workspace. Remove unused ones before adding new.
  </Accordion>

  <Accordion title="Error: 'Short code already exists'">
    Short link slugs are unique across all of linkutm, not just your workspace. Pick a different slug or leave it blank to auto-generate one. A slug that belonged to a deleted link stays reserved for 30 days after deletion, then frees up automatically.
  </Accordion>

  <Accordion title="Click count is zero after testing">
    * Did the click actually resolve? Open the short URL in a private window. -
      Are you within the workspace's retention window?
  </Accordion>

  <Accordion title="Analytics show fewer clicks than expected">
    * **Bots.** Slack/LinkedIn/X fetch your URL once when you paste it for the
      link preview. These show as referrers like `Slack`, `LinkedIn`, etc. -
      **Retention window.** Each workspace has a retention window for click data;
      queries beyond it are silently clipped. - **In-app browsers.** iOS in-app
      browsers (Instagram, TikTok) sometimes don't pass referrer; clicks count,
      attribution doesn't.
  </Accordion>

  <Accordion title="Imported links from Bitly / Rebrandly / Short.io are missing">
    Importer skips conflicts. Check the import result for `errors` - each
    conflict says which slug already exists. Rename the slug at source, then
    re-import.
  </Accordion>

  <Accordion title="Invite link says 'expired'">
    Invites expire 7 days after sending. Resend from the Members page
    (regenerates the token).
  </Accordion>

  <Accordion title="Can't accept an invite - 'sent to a different email'">
    Sign in (or create the account) with the exact email the invite was addressed to. Email match is case-insensitive but must be the same address.
  </Accordion>
</AccordionGroup>

## Still stuck?

[Contact support](/help/contact-support) with: workspace slug, link short code (if relevant), the exact error message, and the time the issue happened.


# Contact support
Source: https://docs.linkutm.com/help/contact-support

How to reach us and what to include for fastest resolution.

## Email

[hello@linkutm.com](mailto:hello@linkutm.com)

## What to include

Skip the back-and-forth - include up front:

<Steps>
  <Step title="Workspace slug">
    Visible in your URL: `app.linkutm.com/{slug}/...`. Include this so we can find your data fast.
  </Step>

  <Step title="What you tried">
    The action you took (clicked X, opened Y page, called API endpoint Z).
  </Step>

  <Step title="What you expected">
    One sentence is enough.
  </Step>

  <Step title="What actually happened">
    Exact error message in quotes. Screenshot if UI. cURL response if API.
  </Step>

  <Step title="When (with timezone)">
    Approximate timestamp + your timezone. Helps us correlate logs.
  </Step>

  <Step title="Browser / device (if UI bug)">
    Chrome 124 on macOS, Safari on iOS, etc.
  </Step>
</Steps>

## Example: a good support email

```
Subject: Cannot create link - "Short code already exists" but slug looks unused

Workspace: client-globex
Time: 2025-05-07 ~14:30 UTC
Browser: Chrome 124, macOS

Steps:
1. Navigated to /client-globex/links
2. Clicked New Link
3. Filled destination + UTMs, set custom slug "q2-launch"
4. Clicked Create

Expected: link created
Actual: "Short code already exists" error toast

I checked our workspace - no link with slug q2-launch exists.
Is it taken in another workspace? Can I see who has it?
```

## Response times

* **Standard support**: business-day reply.
* **Critical (tracking down or system error)**: best-effort same-day.

## Other channels

<CardGroup>
  <Card title="Discord" icon="discord" href="https://go.linkutm.com/discord">
    Live community chat and support.
  </Card>

  <Card title="X / Twitter" icon="twitter" href="https://x.com/linkutm10761">
    Public-friendly questions and updates.
  </Card>

  <Card title="LinkedIn" icon="linkedin" href="https://www.linkedin.com/company/linkutm">
    Product news and case studies.
  </Card>

  <Card title="Facebook" icon="facebook" href="https://www.facebook.com/people/Linkutm/61583414725717/">
    Community page.
  </Card>
</CardGroup>


# Feature requests
Source: https://docs.linkutm.com/help/feature-requests

Tell us what to build next.

## How to submit

Email [hello@linkutm.com](mailto:hello@linkutm.com) with:

1. **What you're trying to do** - the underlying goal, not the proposed solution.
2. **Why** - the workflow or constraint you're hitting today.
3. **Workaround in use** - what you do today (or what's blocking you entirely).
4. **Volume** - how often this comes up, how many links/users affected.

That's enough to evaluate. Don't worry about formatting or wireframes.

## What gets prioritized

In rough order:

<Steps>
  <Step title="Volume × frequency">
    A request blocking 200 users daily beats one blocking 5 users monthly.
  </Step>

  <Step title="Workflow gap">
    Can't accomplish the task at all (high) vs accomplishable but awkward (medium) vs nice-to-have (low).
  </Step>

  <Step title="Strategic fit">
    Aligned with the product direction (link tracking + analytics + team) - fast track. Adjacent (general URL shortener features) - depends. Out-of-scope (CRM, email sending) - usually not.
  </Step>

  <Step title="Build cost">
    Small + high-impact wins prioritization. Large platform changes ship in cycles.
  </Step>
</Steps>

## What we won't build

To set expectations:

* **Email sending / outreach tools** - out of scope.
* **A/B testing of full pages** - UTM differentiation is supported, full page-level testing isn't.
* **CRM features** - out of scope.
* **Anonymous-tracking-evading workarounds** - we honor user privacy laws (GDPR, etc.) and won't add features that fingerprint visitors covertly.

## Track existing requests

We don't currently expose a public roadmap or voting board. If your request matches something in flight, you'll get a heads-up reply.


# Google Analytics 4
Source: https://docs.linkutm.com/integrations/ga4

How linkutm UTM parameters map to GA4 dimensions, how to set up custom dimensions for utm_content and utm_term, and how to verify your attribution is clean.

## What it is

GA4 reads UTM parameters from the destination URL automatically. When a visitor clicks a linkutm link, the UTM values you set travel through the redirect and land on the destination page. GA4 picks them up as traffic source dimensions and attributes the session accordingly.

No special setup is required for basic source/medium/campaign attribution. Custom dimensions are needed if you want `utm_content` and `utm_term` to appear in GA4 reports.

<Note>
  linkutm's [Pixel Tracking](/integrations/pixel-tracking) integration fires a GA4 PageView event on the short link click itself (at the redirect page). UTM attribution covers the destination page session. These are complementary, not the same thing.
</Note>

<Frame>
  <img alt="GA4 Events dashboard - connected state showing Page Views, Link Clicks, Conversions, and Sign Ups stat cards with link performance table" />
</Frame>

***

## Per-link GA4 analytics

Click any link in the GA4 Events dashboard to see its individual event breakdown, views, clicks, conversions, and event timeline.

<Frame>
  <img alt="GA4 per-link detail view - metric cards for page views, link clicks, conversions and conversion rate, GA4 events over time chart with Views/Clicks/Conversions tabs" />
</Frame>

<Frame>
  <img alt="GA4 per-link detail - browsers, devices, screen dimensions, countries, regions, cities, referrers, channels, custom events, age groups, domains and languages breakdown tables" />
</Frame>

***

## How GA4 reads UTMs

GA4 captures five UTM parameters automatically on session start:

| UTM parameter  | GA4 dimension             | Where it shows up                        |
| -------------- | ------------------------- | ---------------------------------------- |
| `utm_source`   | Session source            | Traffic acquisition, Explore             |
| `utm_medium`   | Session medium            | Traffic acquisition, Explore             |
| `utm_campaign` | Session campaign          | Traffic acquisition, Explore             |
| `utm_content`  | Session manual ad content | Explore only (requires custom dimension) |
| `utm_term`     | Session manual term       | Explore only (requires custom dimension) |

Source, medium, and campaign appear in the built-in Traffic Acquisition report out of the box. Content and term require a custom dimension to surface in standard reports.

***

## Channel grouping

GA4 uses `utm_medium` to place sessions into channel groups in the Default Channel Grouping report. If your medium values don't match GA4's rules, sessions land in "Unassigned."

| linkutm medium value  | GA4 Default Channel |
| --------------------- | ------------------- |
| `cpc`                 | Paid Search         |
| `paid-social`         | Paid Social         |
| `email`               | Email               |
| `display`             | Display             |
| `video`               | Paid Video          |
| `affiliate`           | Affiliates          |
| `organic-social`      | Organic Social      |
| `referral`            | Referral            |
| `(none)` + `(direct)` | Direct              |
| Anything else         | Unassigned          |

<Warning>
  Custom medium values like `newsletter`, `podcast`, or `qr` don't match any GA4 default channel rule and will land in Unassigned. This is expected. You can create custom channel groups in GA4 Admin → Data Display → Channel Groups to handle them.
</Warning>

The [UTM naming convention](/playbooks/utm-naming-convention) page lists the recommended medium vocab that maps cleanly to GA4's default channels.

***

## Set up custom dimensions for utm\_content and utm\_term

GA4 does not expose `utm_content` and `utm_term` in standard reports unless you register them as custom dimensions.

<Steps>
  <Step title="Open GA4 Admin">
    Go to **Admin → Data display → Custom definitions**.
  </Step>

  <Step title="Create dimension for utm_content">
    Click **Create custom dimension** and fill in:

    * **Dimension name:** `Manual Ad Content`
    * **Scope:** Session
    * **Event parameter:** `manual_content`

    Save.
  </Step>

  <Step title="Create dimension for utm_term">
    Click **Create custom dimension** again:

    * **Dimension name:** `Manual Term`
    * **Scope:** Session
    * **Event parameter:** `manual_term`

    Save.
  </Step>

  <Step title="Wait for data">
    Custom dimensions only collect data going forward. Allow 24-48 hours before they appear in reports. Historical sessions are not backfilled.
  </Step>

  <Step title="Use in Explore">
    In GA4 Explore, add **Manual Ad Content** or **Manual Term** as a dimension. These are now available across any exploration report.
  </Step>
</Steps>

***

## Verify attribution is working

Use GA4 DebugView to confirm UTMs are being captured before you run a campaign.

<Steps>
  <Step title="Install GA4 DebugView extension">
    Install the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna) Chrome extension and enable it.
  </Step>

  <Step title="Click a test linkutm link">
    Create a test link in linkutm with known UTM values. Click it.
  </Step>

  <Step title="Check DebugView">
    In GA4 Admin → DebugView, look for the `session_start` event. Expand it and confirm:

    * `traffic_source.source` matches your `utm_source`
    * `traffic_source.medium` matches your `utm_medium`
    * `traffic_source.campaign` matches your `utm_campaign`
  </Step>

  <Step title="Verify custom dimensions">
    Look for `manual_content` and `manual_term` parameters on the same event if you set those UTMs on the test link.
  </Step>
</Steps>

***

## Real-world example

A marketing team runs three links for a Q2 campaign and wants to see clean channel splits in GA4.

```
Link 1 (Google Ads):
  utm_source=google
  utm_medium=cpc
  utm_campaign=q2-pricing-relaunch
  utm_content=headline-a
  utm_term=utm+tracking+tool
  → GA4: Paid Search | q2-pricing-relaunch

Link 2 (Newsletter):
  utm_source=newsletter
  utm_medium=email
  utm_campaign=q2-pricing-relaunch
  utm_content=hero-cta
  → GA4: Email | q2-pricing-relaunch

Link 3 (LinkedIn Ads):
  utm_source=linkedin
  utm_medium=paid-social
  utm_campaign=q2-pricing-relaunch
  utm_content=cta-book-demo
  → GA4: Paid Social | q2-pricing-relaunch
```

In GA4 Traffic Acquisition, filter by `campaign = q2-pricing-relaunch` to see all three channels side by side. In Explore, add Manual Ad Content to compare `headline-a` vs `hero-cta` vs `cta-book-demo` on conversions.

***

## Common mistakes

<AccordionGroup>
  <Accordion title="Sessions showing as Direct instead of the expected channel">
    Three causes: the UTMs were stripped from the URL before GA4 loaded (check for URL rewrites or redirects that drop query params), the visitor's browser blocked the GA4 tag, or cookie consent blocked the tag from firing. Use DebugView to rule out the first cause.
  </Accordion>

  <Accordion title="Source showing as the short link domain instead of utm_source">
    If a visitor clicks `go.yourdomain.com/xyz` and GA4 fires on the destination page, GA4 may record the short link domain as the referrer instead of reading the UTM. This happens when linkutm's redirect passes the referrer header. Fix: add your short link domain to the **Referral exclusion list** in GA4 Admin → Data streams → Configure tag settings → List unwanted referrals.
  </Accordion>

  <Accordion title="utm_campaign shows as (not set) in reports">
    The UTM was missing from the link or was stripped during redirect. Check the actual destination URL in browser dev tools → Network tab → look at the final URL after redirect to confirm `utm_campaign` is present.
  </Accordion>

  <Accordion title="Channel grouping shows Unassigned for paid traffic">
    Your `utm_medium` value doesn't match GA4's channel rules. `paid-social` and `cpc` are correct. `PaidSocial`, `paid_social`, or `social` are not. See the channel grouping table above.
  </Accordion>

  <Accordion title="utm_content not appearing in Explore">
    The custom dimension for `manual_content` has not been created yet, or was created after the sessions you're looking at (no backfill). Create the dimension and wait 24-48 hours for new data.
  </Accordion>
</AccordionGroup>

***

## Edge cases

<Note>
  **Internal traffic.** If you or your team click linkutm links during testing, those sessions will appear in GA4. Define an internal traffic rule in GA4 Admin → Data streams → Configure tag settings → Define internal traffic to exclude your IP ranges.
</Note>

<Note>
  **Cross-domain tracking.** If your destination page is on a different domain from your short link (e.g. `go.yourdomain.com` redirects to `app.yourproduct.com`), GA4 may count the visit as a new session and lose the UTM. Add the short link domain to the cross-domain list in GA4 Admin → Data streams → Configure tag settings → Configure your domains.
</Note>

<Note>
  **UTM parameters persist for the session only.** GA4 attributes UTMs to the session in which the user first arrived. If the same user returns later without UTMs, GA4 does not re-attribute that session. This is standard GA4 behavior, not a linkutm issue.
</Note>


# Pixel Tracking
Source: https://docs.linkutm.com/integrations/pixel-tracking

Connect ad pixels (Facebook, GA4, TikTok, LinkedIn, and more) to fire automatically on every link click.

## What it is

Pixel tracking lets you attach one or more ad-network pixels to your workspace. When a visitor clicks any linkutm short URL, the system fires those pixels **before** redirecting - so you get a PageView event in your ad platform without touching the destination page.

## Supported platforms

| Platform             | ID format        | Example                |
| -------------------- | ---------------- | ---------------------- |
| Google Analytics 4   | Measurement ID   | `G-XXXXXXXXXX`         |
| Facebook Pixel       | Numeric pixel ID | `1234567890123456`     |
| Google Tag Manager   | Container ID     | `GTM-XXXXXXX`          |
| Twitter / X          | Tag ID           | `o0abc`                |
| LinkedIn Insight Tag | Partner ID       | `123456`               |
| TikTok Pixel         | Pixel ID         | `XXXXXXXXXXXXXXXXXX`   |
| Pinterest Tag        | Tag ID           | `1234567890123`        |
| Snapchat Pixel       | UUID             | `abc123-def456-ghi789` |

## How to set up a pixel

<Steps>
  <Step title="Open Integrations">
    **Settings → Integrations** (workspace settings, not account settings).
  </Step>

  <Step title="Add Pixel">
    Click **Add Pixel** in the top-right corner.
  </Step>

  <Step title="Fill in the form">
    * **Name** - internal label (e.g. `Facebook Pixel - Main`, `GA4 - linkutm`). Not shown to visitors.
    * **Platform** - select from the supported list.
    * **Pixel ID** - the ID from your ad platform. Use **How to find your ID** link for platform-specific instructions.
  </Step>

  <Step title="Save">
    The pixel appears in **Connected Pixels**, enabled by default.
  </Step>
</Steps>

<Frame>
  <img alt="Settings > Integrations - Add Tracking Pixel modal with Name, Platform (Facebook Pixel), and Pixel ID fields; available integrations in background" />
</Frame>

<Frame>
  <img alt="Settings > Integrations - Connected Pixels section showing Facebook Pixel enabled, with integration grid and Connected badge" />
</Frame>

## How pixels fire

Every enabled workspace pixel fires by default on every link click. You can override this per-link (see below).

The system injects a hidden redirect page that:

1. Fires all applicable pixel scripts (PageView event for each platform).
2. Immediately redirects the visitor to the destination URL.

This happens in the background and the visitor is forwarded to the destination right away.

## Per-link pixel control

When creating or editing a link, open the **Pixels** panel in the link builder.

* **No selection** (default) - all enabled workspace pixels fire.
* **Select specific pixels** - only the checked pixels fire for that link.
* **Deselect all** - clears the override; falls back to workspace default (all fire).

Use this when running multi-channel campaigns and you want only the relevant platform pixel to fire on each link variant (e.g. only the Facebook pixel fires on links distributed via Facebook ads).

<Frame>
  <img alt="Tracking Pixels panel in the link builder - Facebook Pixel - Main checkbox selected, Apply Pixels button" />
</Frame>

## Enabling / disabling pixels

Toggle the switch next to any pixel in **Settings → Integrations** to disable it workspace-wide without deleting it. Disabled pixels never fire, regardless of per-link selection.

## Real-world example

You run paid campaigns across Facebook, Google, and TikTok.

```
Workspace pixels configured:
  - Facebook Pixel - Main   (enabled)
  - GA4 - linkutm           (enabled)
  - TikTok Pixel - Q2       (enabled)

Link: go.acme.com/fb-q2
  Pixels selected: Facebook Pixel - Main only
  → Only Facebook pixel fires on click

Link: go.acme.com/tiktok-q2
  Pixels selected: TikTok Pixel - Q2 only
  → Only TikTok pixel fires on click

Link: go.acme.com/email-q2
  Pixels selected: (none - workspace default)
  → All three pixels fire on click
```

Your ad platforms each get accurate PageView events without any changes to the destination landing page.

## Common mistakes

<AccordionGroup>
  <Accordion title="Pixel fires but conversion isn't attributed">
    linkutm fires a **PageView** event. Conversion events (Purchase, Lead, etc.) must be fired separately on your destination page. linkutm handles top-of-funnel click attribution; your site handles the downstream conversion events.
  </Accordion>

  <Accordion title="Wrong Pixel ID format">
    Each platform has a distinct ID shape. Facebook IDs are all-numeric (15-16 digits). GA4 IDs start with `G-`. GTM IDs start with `GTM-`. Paste from the platform's dashboard - don't type from memory.
  </Accordion>

  <Accordion title="Pixel shows as active but no data in ad platform">
    Ad blockers and iOS 14.5+ ATT restrictions suppress pixel fires in-browser. This is expected and not a linkutm bug. Use server-side Conversions API on your destination site to recover blocked signals.
  </Accordion>

  <Accordion title="Added pixel but it's not firing on existing links">
    Existing links with an explicit pixel selection (even an empty one) are not automatically updated when you add a new workspace pixel. Edit those links and clear the per-link pixel selection to restore workspace default behavior.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Plan limits.** Advanced pixel integrations (GA4 specifically) may be gated to paid plans. The integrations page shows which platforms require an upgrade.
</Note>

<Note>
  **Multiple pixels from the same platform.** You can connect more than one pixel from the same platform (e.g. two Facebook pixels for two ad accounts). Each is tracked independently and both fire unless you override per-link.
</Note>

<Note>
  **Deleting a pixel.** Deleting a pixel removes it from all links permanently. The per-link selection for that pixel is cleared. Historical link clicks are not retroactively affected - they already fired when they occurred.
</Note>


# Custom domains
Source: https://docs.linkutm.com/link-shortening/custom-domains

Set up a branded short domain (e.g., go.acme.com) via CNAME.

## What it is

Use a domain you own as the short-URL host. `go.acme.com/q2-launch` instead of the system default. Your SSL certificate is set up automatically once the CNAME verifies.

## When to use it

* Customer-facing channels: email, social, podcasts, packaging.
* Anywhere the URL is read by a human and brand trust matters.
* Multi-brand agencies running per-client domains.

Skip it for ads-only links - auto-generated codes on the system domain are fine and the URL isn't visible.

## How to set one up

<Steps>
  <Step title="Pick a subdomain">
    Recommended: a fresh subdomain like `go.acme.com`, `link.acme.com`, `acme.link`. Don't use a domain or subdomain already serving production traffic.
  </Step>

  <Step title="Add the domain in linkutm">
    Sidebar → **Domains** → **Add Domain**. Enter `go.acme.com`. The system creates the record in `pending` status and shows you the CNAME target.
  </Step>

  <Step title="Configure DNS">
    In your DNS provider (Cloudflare, Route 53, etc.):

    | Type    | Name | Value               | TTL      |
    | ------- | ---- | ------------------- | -------- |
    | `CNAME` | `go` | `cname.linkutm.com` | 300-3600 |

    The exact CNAME target is shown in the Domains page after you add the domain.

    <Warning>If you use Cloudflare, set the record to **DNS only** (gray cloud), not proxied. Proxying breaks SSL provisioning.</Warning>
  </Step>

  <Step title="Verify">
    Click **Verify** on the domain row. The system runs a CNAME lookup against your DNS. Status flips to `active` once the CNAME points correctly. SSL is issued automatically within \~1 minute.
  </Step>

  <Step title="Set as default (optional)">
    Mark the domain as **Default** so new links use it without picking. Only one default per workspace.
  </Step>
</Steps>

<Frame>
  <img alt="Domains page - list of custom and system domains with Verified status badges" />
</Frame>

<Frame>
  <img alt="Add Custom Domain modal - domain field, optional default redirect, and DNS setup note" />
</Frame>

## Real-world example

Acme has two brands, two domains:

```
Workspace: Acme Main
Domain:    go.acme.com  (default, verified, active)

Workspace: Acme Pro
Domain:    pro.acme.link  (default, verified, active)
```

Marketers in Acme Main create links on `go.acme.com`; Pro team on `pro.acme.link`. Per-workspace branding stays clean.

## Common mistakes

<AccordionGroup>
  <Accordion title="Cloudflare proxy enabled">
    Orange-cloud (proxied) stops verification and the secure certificate from working. Set to gray-cloud (DNS only).
  </Accordion>

  <Accordion title="Apex domain (no subdomain)">
    `acme.com` directly is rarely a good idea - most DNS providers won't allow CNAME at apex, and it conflicts with your main site. Use a subdomain.
  </Accordion>

  <Accordion title="Verifying before DNS propagates">
    DNS changes can take minutes to hours. If verification fails, wait a few minutes and try again.
  </Accordion>

  <Accordion title="Deleting a domain that has links">
    Returns an error if any link uses it. Reassign or delete the links first.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Domain limit.** Each workspace has a maximum number of custom domains. If you reach it, remove an unused one before adding another.
</Note>

<Note>
  **Renaming a domain.** Editing the `domain` field resets verification. Re-verify after the rename.
</Note>

<Note>
  **System default cannot be deleted.** It exists for new workspaces to function out of the box.
</Note>


# How redirects work
Source: https://docs.linkutm.com/link-shortening/overview

How linkutm shortens URLs, what domain options exist, and how the redirect works.

Every link in linkutm gets a short URL: `{domain}/{shortCode}`. Visiting it triggers a redirect to the destination URL with all UTMs appended. The click is recorded with the visitor's location, device, browser, and referrer.

## When to use it

Always - there's no "long-URL only" mode. Pick which short domain to use per link.

## Domain options

<Tabs>
  <Tab title="System default">
    Every workspace gets a default short domain on creation. No setup needed. Useful for ads where the slug isn't visible to humans (Google Ads, Meta Ads).
  </Tab>

  <Tab title="Custom branded domain">
    Bring your own domain (`go.acme.com`, `acme.link`, etc.). A quick DNS setup connects it, and we walk you through it. Branded short URLs increase click-through rates and trust on visible channels (email, social, podcasts).

    See [Custom domains](/link-shortening/custom-domains).
  </Tab>
</Tabs>

## How the redirect works

<Steps>
  <Step title="Visitor clicks the short link">
    Their browser opens `go.acme.com/q2-launch`.
  </Step>

  <Step title="linkutm validates the link">
    Checks whether the link is active. An expired link redirects to its fallback URL, or shows an error page if no fallback is set. Archived links keep redirecting normally.
  </Step>

  <Step title="Click is recorded">
    Country, city, device type, browser, OS, and referrer are captured. This is what populates your analytics.
  </Step>

  <Step title="UTMs are appended to the destination URL">
    The visitor's browser is sent to your destination URL with all UTM parameters attached.
  </Step>

  <Step title="Pixels fire (if configured)">
    If you've added pixels (Facebook, TikTok, GTM, etc.) to the link or workspace, they fire before the final redirect.
  </Step>
</Steps>

## Real-world example

A podcast sponsor read:

> "Visit go.acme.com/podcast for 20% off."

What happens:

* Listener types `go.acme.com/podcast`.
* linkutm logs the click (country = listener's, device = mobile/desktop, referrer = direct).
* Redirects to `https://acme.com/offer?utm_source=podcast&utm_medium=audio&utm_campaign=q2_launch`.
* The acme.com landing page sees the UTMs and reports them to GA.

## Common mistakes

<AccordionGroup>
  <Accordion title="Sharing the destination URL with UTMs hard-coded">
    Defeats tracking - no centralized click count, no per-channel attribution, no easy edit. Always share the short URL.
  </Accordion>

  <Accordion title="Using an insecure (http) short domain">
    Some platforms (LinkedIn, Slack) won't show previews for insecure links. linkutm always uses secure `https` links, and the security certificate is set up automatically for verified custom domains.
  </Accordion>

  <Accordion title="Pointing a domain that's already in use">
    If `go.acme.com` is already running a real site, pointing it to linkutm will break that site. Use a fresh subdomain instead.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Bare domain.** Visiting `https://go.acme.com/` with no slug after it shows a not-found page. Always share the full short URL including the slug.
</Note>

<Note>
  **Archived links keep redirecting.** Archiving only removes a link from default list views; the short URL still resolves and clicks are still recorded.
</Note>


# Create a link
Source: https://docs.linkutm.com/links/create-link

The full link creation flow: destination, UTMs, organization, advanced options.

Every campaign URL you build in linkutm gets a short link. Visitors click the short URL, the click is recorded, and they land on your destination with UTM parameters attached. There is no untracked mode.

<Frame>
  <img alt="Links dashboard - list view showing link title, short URL, destination, tags, click count, and created date" />
</Frame>

<Frame>
  <img alt="Links dashboard - card/grid view showing the same links as cards with click counts" />
</Frame>

## When to use it

* Every campaign URL goes through here. There's no "untracked" mode.
* Use [bulk import](#bulk-and-import) instead if you have 50+ links to migrate.
* Use a [template](/utm-templates/overview) if you create the same shape of link weekly.

## How to create one

<Steps>
  <Step title="Open the builder">
    Sidebar → **Links** → **Create Link**.

    <Frame>
      <img alt="Create Link modal - Destination URL, Short Link, Title, Tags, Folder, Comments, QR preview, link preview card, and UTM/Advanced/Pixels tabs" />
    </Frame>
  </Step>

  <Step title="Destination URL">
    The page you're driving traffic to. Must include `https://` (or `http://`). Query strings already on the URL are preserved - UTMs append after.
  </Step>

  <Step title="Domain">
    Pick which short domain to use. Defaults to the workspace's default domain. Only **verified, enabled** custom domains are selectable.
  </Step>

  <Step title="Custom slug (optional)">
    The path after your domain. Leave blank for an auto-generated short code. Type your own for branded slugs (`q2-launch`).

    <Warning>Short codes are unique across the entire system. If your slug is taken, you'll see *"Short code already exists"* - pick another.</Warning>
  </Step>

  <Step title="Organize (optional)">
    Drop into a [folder](/links/folders-and-tags) and add [tags](/links/folders-and-tags). Both are workspace-scoped and useful for filtering large link lists.
  </Step>

  <Step title="Description (optional)">
    Only for internal reference, never shown to visitors.
  </Step>

  <Step title="UTM parameters">
    Fill from the autocomplete (powered by your [parameter library](/utm-parameters/overview)) or type freely. Workspace [UTM rules](/utm-rules/overview) clean values on save (lowercase, space → underscore, etc).

    <Frame>
      <img alt="UTM parameters section in the link builder - source, medium, campaign, term, and content fields with autocomplete" />
    </Frame>
  </Step>

  <Step title="Advanced (optional)">
    Open the advanced section for password, expiration, click limits, scheduling, link cloaking, iOS/Android redirect, fallback URL, and link preview overrides.

    <Frame>
      <img alt="Advanced settings panel - Timezone picker, Activation Date and Time, Expiration Date and Time, Click Limit, Fallback Redirect URL, Link Cloaking, iOS redirect, and Android redirect fields" />
    </Frame>
  </Step>

  <Step title="Create">
    Hit **Create**. Link is live, Short URL is active, click count starts at zero.
  </Step>
</Steps>

## Real-world example

Running a Google Ads campaign for a Q2 product launch, brand keywords variant:

```
Destination:  https://acme.com/products/widget
Title:        Q2 Launch - Google Search - Brand
utm_source:   google
utm_medium:   cpc
utm_campaign: q2_launch
utm_term:     acme_widget
utm_content:  headline_a
Custom slug:  q2-acme
Folder:       Q2 Launch
Tags:         google-ads, paid-search
```

Final short URL: `go.acme.com/q2-acme` → redirects to the full UTM-tagged destination.

## Common mistakes

<AccordionGroup>
  <Accordion title="Spaces or capitals in UTM values">
    `Summer Sale` becomes `summer_sale` automatically (force-lowercase + space-replacement are on by default). But if you turned those rules off, you'll get split campaign rows in GA. Leave the rules on unless you have a reason.
  </Accordion>

  <Accordion title="Forgetting `https://`">
    Required. The builder won't accept a bare `example.com`.
  </Accordion>

  <Accordion title="Using a slug another workspace owns">
    Slugs are global, not workspace-local. Creative slugs avoid collisions: `acme-q2` beats `launch`.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Workspace usage limits.** Workspaces have a maximum number of total links. When you hit the limit, link creation fails with a clear message and the workspace owner is notified by email when the link creation quota is near maximum.
</Note>

<Note>
  **Unverified domain.** You cannot create a link on a custom domain that hasn't been verified yet. Use the system default until [verification](/link-shortening/custom-domains) succeeds.
</Note>

## Filtering and bulk actions

Use the links dashboard to filter, sort, and act on multiple links at once.

<Frame>
  <img alt="Filters panel - Source dropdown (Google, Facebook, Twitter, LinkedIn) and Medium dropdown for narrowing the links list" />
</Frame>

<Frame>
  <img alt="Display settings panel - Ordering options, Show archived toggle, and Display Properties checkboxes" />
</Frame>

<Frame>
  <img alt="Date range picker - preset options list alongside a dual-month calendar for custom date ranges" />
</Frame>

Select links in the list to reveal bulk actions - Export, Archive, Tag, Move, Delete.

<Frame>
  <img alt="Links dashboard with all links selected - bulk action bar showing Export, Archive, Tag, Move, and Delete buttons" />
</Frame>

## Bulk and import

For 50+ links, use:

* **CSV import** - UI flow under Links → Import.
* **Bitly / Rebrandly / Short.io migration** - paste your API key, the system pulls links and recreates them. Original slugs are preserved when not taken; conflicts are skipped with a per-link error.

<Frame>
  <img alt="Import/Export dropdown - Import options (Bitly, Rebrandly, Short.io, CSV) and Export as CSV" />
</Frame>

**CSV import flow:**

<Frame>
  <img alt="CSV Import step 1 - drag-and-drop upload area with Download sample CSV button" />
</Frame>

<Frame>
  <img alt="CSV Import step 2 - column mapping view where CSV columns are mapped to linkutm UTM fields, with Preview and check conflicts button" />
</Frame>

<Frame>
  <img alt="CSV Import step 3 - review screen showing 25 links, 0 conflicts, Ready status, and Import 25 ready links button" />
</Frame>

**Export:**

<Frame>
  <img alt="Export as CSV modal - Date Range picker and column checkboxes (Title, Clicks, UTM fields, Created Date, Tags, Folder) with Export button" />
</Frame>


# Device targeting
Source: https://docs.linkutm.com/links/device-targeting

Send mobile visitors to a different destination based on their device.

Device targeting lets you set separate destination URLs for iPhone/iPad visitors and Android visitors. Everyone else (desktop, other mobile devices) goes to the standard destination. All three paths are tracked as clicks in analytics. UTM parameters set on the link are appended to the iOS and Android URLs as well as the standard destination.

## When to use it

* Sending iOS visitors to your App Store listing and Android visitors to Google Play, while desktop visitors land on your website.
* Directing mobile users to a mobile-optimised version of a page that desktop users don't need.
* Running a campaign where the destination differs by device without needing separate links.

## How to use it

<Steps>
  <Step title="Open Advanced">
    In the create or edit link panel, click **Advanced** in the bottom bar.

    <Frame>
      <img alt="Advanced settings panel showing iOS Redirect URL and Android Redirect URL fields" />
    </Frame>
  </Step>

  <Step title="Set the iOS URL">
    In the **iOS Redirect URL** field, enter the full URL for iPhone and iPad visitors. Leave blank to send iOS visitors to the standard destination.
  </Step>

  <Step title="Set the Android URL">
    In the **Android Redirect URL** field, enter the full URL for Android visitors. Leave blank to send Android visitors to the standard destination.
  </Step>

  <Step title="Save">
    The redirect is stored on the link. Routing happens automatically on every visit.
  </Step>
</Steps>

## Real-world example

A mobile app launch campaign with one short link covering all devices:

```
Destination:    https://acme.com/app                          (desktop visitors)
iOS URL:        https://apps.apple.com/app/acme               (iPhone / iPad)
Android URL:    https://play.google.com/store/apps/acme       (Android)
utm_source:     instagram
utm_campaign:   app_launch_jun25
```

One link in the bio. iOS users go to App Store, Android users go to Google Play, everyone else lands on the web page. Every visitor arrives with `utm_source=instagram` and `utm_campaign=app_launch_jun25` appended, whichever destination they hit.

## Common mistakes

<AccordionGroup>
  <Accordion title="Adding UTM parameters manually to device URLs">
    linkutm appends the link's UTM parameters to the iOS and Android URLs automatically. There is no need to build tracking parameters into those URLs. Set UTMs once on the link and leave device URLs clean.
  </Accordion>

  <Accordion title="Leaving one field blank unintentionally">
    If you fill iOS URL but leave Android URL blank, Android visitors go to the standard destination. That may be intentional, but double-check before saving.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Detection is based on the visitor's device, not browser.** iPad counts as iOS. Android tablets count as Android. Desktops, Windows phones, and other devices fall through to the standard destination.
</Note>

<Note>
  **Password-protected links.** If the link has a password, device routing happens after the visitor enters the correct password.
</Note>


# Folders & Tags
Source: https://docs.linkutm.com/links/folders-and-tags

Organize and label links using folders for primary grouping and tags for cross-cutting attributes.

<Tip>
  **Folders vs tags:** Use folders for primary grouping (one per link), such as campaign, client, or channel. Use tags for cross-cutting labels a link can belong to many of, such as status, quarter, or experiment flag. Think of a folder as the filing cabinet drawer and tags as sticky notes on the file.
</Tip>

Both folders and tags are managed from **Sidebar → Folders & Tags**.

<Frame>
  <img alt="Folders and Tags page - folder list with color indicators and tags panel" />
</Frame>

## Folders

Folders are flat containers for organizing links inside a workspace. Each folder is separate; folders don't support nesting. Each link belongs to zero or one folder. Unfiled links live in **Unsorted**.

### When to use folders

* 30+ links per workspace.
* Per-campaign or per-client grouping.
* Anytime your link list takes more than a glance to scan.

If you only need light grouping, tags are cheaper - links can have many tags but only one folder.

### How to use folders

<Steps>
  <Step title="Create a folder">
    Sidebar → **Folders & Tags**. Name it (case-insensitive unique per workspace), pick a color.
  </Step>

  <Step title="Set a default">
    Mark one folder as **Default**. The link builder uses this as the pre-selected folder when you create a new link. Only one default at a time per workspace.
  </Step>

  <Step title="Move links in">
    From the link list: select links → **Move to folder**.
  </Step>
</Steps>

<Frame>
  <img alt="Create Folder modal - name field and 8-color picker" />
</Frame>

### Folder common mistakes

<AccordionGroup>
  <Accordion title="One mega folder">
    Putting 800 links in "All Campaigns" defeats the point. Split links into separate folders by campaign, client, or quarter.
  </Accordion>

  <Accordion title="Same name twice">
    Folder names are case-insensitive unique per workspace. `Email` and `email` collide.
  </Accordion>

  <Accordion title="Expecting subfolders">
    Folders don't contain other folders. Use clear folder names, such as `Q2 Launch - Email`, or use tags for cross-cutting labels.
  </Accordion>
</AccordionGroup>

***

## Tags

Tags are color-coded labels on links. Each link can have many tags. Each tag belongs to one workspace. Use them for any cross-cutting attribute that doesn't fit a single flat folder.

### When to use tags

* Status: `active`, `paused`, `draft`.
* Channel cohort: `paid-search`, `paid-social`, `email`.
* Quarterly review: `q2-2025`, `q3-2025`.
* A/B variants you might compare across campaigns.

### How to use tags

<Steps>
  <Step title="Create a tag">
    Sidebar → **Folders & Tags** → **Create tag**. Name it (case-insensitive unique per workspace), pick a color (default orange).
  </Step>

  <Step title="Apply on a link">
    From the link builder or the Links list: select the link → **Tags** → pick one or more.
  </Step>

  <Step title="Bulk-tag">
    On the Links list: select multiple links → **Bulk Tag** → add tags.

    * **Add** mode appends without removing existing tags.
  </Step>
</Steps>

<Frame>
  <img alt="Create Tag modal - name field and color picker" />
</Frame>

### Tag common mistakes

<AccordionGroup>
  <Accordion title="Folders pretending to be tags">
    Creating folders for each status (`active`, `paused`)? Use tags. Folders are separate containers for links, not nested hierarchies.
  </Accordion>

  <Accordion title="Duplicate names">
    Tag names are case-insensitive unique per workspace. `Email` and `email` collide.
  </Accordion>

  <Accordion title="Color overload">
    More than 8-10 colors becomes visual noise. Reuse colors with distinct names.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  Both tags and Folders can be renamed from the 3 dot menu in the Folders & Tags panel.
</Note>

<Note>
  **Deleting a tag** removes it from every link automatically. Click history is unaffected.
</Note>

## Real-world example

Agency managing a client campaign:

```text theme={null}
Folders:
Acme Corp - Paid Search
Acme Corp - Paid Social
Acme Corp - Email

Tags applied across folders:
experiment    (purple)   - A/B test variants
seasonal      (yellow)   - tied to a season or holiday
archive-q1    (gray)     - last quarter, kept for reporting
```

A single link can live in `Acme Corp - Email` and also carry `experiment` + `seasonal` tags. Filter by tag to see cross-folder cohorts instantly.


# Geo targeting
Source: https://docs.linkutm.com/links/geo-targeting

Redirect visitors to different destinations based on their country.

Geo targeting lets you set a separate destination URL for each country. Visitors from a country with a rule go to that URL. Everyone else goes to the standard destination. All paths are tracked as clicks in analytics. UTM parameters set on the link are appended to country URLs as well as the standard destination.

## When to use it

* Sending US visitors to a pricing page in USD and EU visitors to one in EUR.
* Directing visitors to a country-specific landing page without creating separate links.
* Complying with regional content restrictions by routing certain countries to an appropriate page.
* Running localised campaigns from a single shared link.

## How to use it

<Steps>
  <Step title="Open the link panel">
    Create a new link or open an existing one for editing.

    <Frame>
      <img alt="Link creation modal with UTM, Advanced, QR Code, Pixels, and Targeting tabs in the bottom bar" />
    </Frame>
  </Step>

  <Step title="Open Targeting">
    Click **Targeting** in the bottom bar. The geo targeting panel opens.
  </Step>

  <Step title="Enable redirect by country">
    Toggle **Redirect by country** on.
  </Step>

  <Step title="Add country rules">
    Click **+ Add location**. Select a country from the dropdown and enter the destination URL for that country. Repeat for each country you want to target.

    <Frame>
      <img alt="Geo targeting panel showing country dropdown and destination URL fields for United States, Canada, and Australia" />
    </Frame>
  </Step>

  <Step title="Apply and save">
    Click **Apply Targeting**, then save or update the link. Rules are not applied until the link is saved.
  </Step>
</Steps>

## Real-world example

A SaaS product running one campaign link across three regions:

```
Destination:       https://acme.com/pricing          (all other countries)
United States:     https://acme.com/pricing-usd
Canada:            https://acme.com/pricing-cad
Australia:         https://acme.com/pricing-aud
utm_source:        email
utm_campaign:      pricing_launch_jul26
```

US, CA, and AU visitors each land on a localised pricing page. Every other country hits the default. Every visitor arrives with `utm_source=email` and `utm_campaign=pricing_launch_jul26` appended, whichever destination they hit. All clicks tracked under one link.

## Common mistakes

<AccordionGroup>
  <Accordion title="Clicking Apply Targeting but not saving the link">
    Apply Targeting saves the rules to the form, not to the link. The note in the panel confirms this. Always click **Update link** on the main screen after applying.
  </Accordion>

  <Accordion title="Leaving the toggle off">
    Country rules have no effect if Redirect by country is toggled off. The link falls back to the standard destination for all visitors regardless of rules set.
  </Accordion>

  <Accordion title="Adding UTM parameters manually to country URLs">
    linkutm appends the link's UTM parameters to country URLs automatically. There is no need to build tracking parameters into those URLs. Set UTMs once on the link and leave country URLs clean.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Country not in the list.** Visitors from a country with no rule go to the standard destination. There is no fallback rule or catch-all country option.
</Note>

<Note>
  **VPN and proxy visitors.** Country detection uses the visitor's IP. Visitors on a VPN may resolve to the wrong country and receive an unintended destination.
</Note>


# Link cloaking
Source: https://docs.linkutm.com/links/link-cloaking

Keep your short link in the address bar while showing the destination page behind it.

Link cloaking keeps your short URL visible in the visitor's address bar for the entire session. The destination page loads inside your short link's URL, so the visitor never sees where the link actually goes.

## When to use it

* White-labelling a third-party page under your own branded domain.
* Sharing an affiliate link without exposing the raw affiliate URL to the visitor.
* Keeping a campaign destination confidential while still tracking clicks.

## How to use it

<Steps>
  <Step title="Open Advanced">
    In the create or edit link panel, click **Advanced** in the bottom bar.
  </Step>

  <Step title="Turn on Link Cloaking">
    Find the **Link Cloaking** toggle and switch it on. linkutm checks whether the destination allows this and shows a warning if it doesn't.

    <Frame>
      <img alt="Advanced settings panel showing Link Cloaking toggle" />
    </Frame>
  </Step>

  <Step title="Review any warning">
    If the destination blocks cloaking, a yellow warning appears. You can still save the link, but visitors may see a blank page. Choose a different destination or turn cloaking off.
  </Step>

  <Step title="Save the link">
    The setting is stored on the link. Every visit will now show your short URL in the address bar.
  </Step>
</Steps>

## Real-world example

An affiliate publisher promoting a partner's product page under their own short domain:

```
Destination:  https://partner.com/products/widget
Short link:   go.yoursite.com/widget
Cloaking:     on
```

Visitors see `go.yoursite.com/widget` throughout. The partner's page loads normally.

## Common mistakes

<AccordionGroup>
  <Accordion title="Using it on Google, Facebook, or payment pages">
    These sites don't allow being displayed inside another page, so cloaking won't work. Visitors see a blank page. linkutm warns you when this is detected. Pay attention to that warning before saving.
  </Accordion>

  <Accordion title="Expecting UTM parameters to be hidden too">
    Cloaking hides the destination URL from the address bar. UTM parameters are still appended to the destination URL and recorded in analytics. They are not shown to the visitor, but they are still present.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Not all sites allow this.** Whether cloaking works depends on the destination site's settings, not linkutm. linkutm runs a compatibility check when you enable it and warns you if the site blocks embedding.
</Note>


# Link scheduling
Source: https://docs.linkutm.com/links/link-expiration

Control when a link becomes active, when it stops, and where it sends visitors after it expires.

Two date controls let you define the active window for a link:

* **Activation Date & Time**: the link does not redirect to its destination until this moment. Before then, visitors go to the fallback URL if one is set, otherwise they see a "not found" response.
* **Expiration Date & Time**: after this moment, the link stops sending visitors to the destination. They go to the fallback URL if one is set, otherwise they see a "not found" response.
* **Fallback URL**: an alternate destination the link redirects to once it has expired, or if someone clicks the link before the activation date.
* **Click limit**: a maximum number of clicks. Once hit, the link stops redirecting.

You can set any combination of these. A link with only an activation date goes live on schedule and stays live forever. A link with only an expiration date is live immediately and cuts off at the set time.

## When to use it

* Pre-building campaign links days in advance and scheduling them to go live at a precise moment.
* Running a limited-time promotion that starts and ends automatically with no manual intervention.
* Setting a hard cutoff on a flash sale or embargoed announcement.
* Capping a giveaway link at a specific number of clicks.
* Sending visitors somewhere useful (a waitlist, a homepage) after a campaign ends.

## How to use it

<Steps>
  <Step title="Open Advanced">
    In the create or edit link panel, click **Advanced** in the bottom bar.
  </Step>

  <Step title="Pick a timezone">
    Select your timezone from the dropdown. linkutm defaults to your browser's detected timezone. All dates and times you enter are interpreted in this timezone.
  </Step>

  <Step title="Set an Activation Date & Time (optional)">
    Fill in **Activation Date & Time** if you want the link to start at a future moment. Leave blank for the link to go live immediately on save.
  </Step>

  <Step title="Set an Expiration Date & Time (optional)">
    Fill in **Expiration Date & Time** if you want the link to stop at a set moment. If an activation date is also set, expiration must be later than activation.
  </Step>

  <Step title="Set a click limit (optional)">
    Type a number in **Click Limit**. The counter increments on each real visit. Once the limit is reached, the link stops redirecting.
  </Step>

  <Step title="Set a fallback URL (optional)">
    Enter a **Fallback Redirect URL**. After the link expires (by date or click limit), or if someone clicks before the activation date, visitors are sent here instead of seeing a "not found" page.
  </Step>

  <Step title="Save">
    The schedule is stored. The link activates, expires, and redirects to fallback on its own.
  </Step>
</Steps>

<Frame>
  <img alt="Advanced settings panel - Timezone picker, Activation Date and Time, Expiration Date and Time, Click Limit, and Fallback Redirect URL fields" />
</Frame>

## Real-world example

A Black Friday flash sale running for 48 hours, capped at 500 clicks, with a fallback to the main store:

```
Destination:      https://acme.com/bf-50-off
Activation:       2025-11-28 00:00  (New York / ET)
Expiration:       2025-11-29 23:59  (New York / ET)
Click limit:      500
Fallback URL:     https://acme.com/shop
utm_source:       email
utm_campaign:     bf_flash_2025
```

Before November 28 midnight ET, the link isn't active yet, so visitors are sent to the fallback `acme.com/shop`. After November 29 at midnight ET, or after 500 clicks (whichever comes first), the link expires and visitors are again sent to `acme.com/shop`. In between, the link serves its destination.

## Common mistakes

<AccordionGroup>
  <Accordion title="Setting expiration before activation">
    If the expiration date is the same as or earlier than the activation date, the link never becomes active. The builder blocks this and shows a validation error. Check that expiration is set to a later time than activation.
  </Accordion>

  <Accordion title="Using the wrong timezone">
    The timezone picker defaults to your browser timezone. If you're scheduling for a different region, switch the timezone first. Otherwise your go-live moment will be off.
  </Accordion>

  <Accordion title="Setting a click limit on a high-traffic link">
    Clicks can spike fast. A limit of 100 on a link that suddenly gets 50,000 impressions cuts off almost everyone. Set the limit only when a hard cap is the actual intent.
  </Accordion>

  <Accordion title="Expecting past clicks to disappear after expiry">
    Past clicks stay in analytics. Expiration only stops new redirects.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Activation and expiration are both optional.** Set one, both, or neither. A link with no activation date goes live on save. A link with no expiration date stays live indefinitely.
</Note>

<Note>
  **Click limit vs. expiration.** Both stop the link when triggered. If both are set, whichever condition is hit first stops the link. The fallback URL applies in both cases.
</Note>

<Note>
  **Existing links.** You can add or change a schedule on a link that is already live. Setting an activation date in the past is treated as already active.
</Note>

<Note>
  **UTM parameters do not carry to the fallback URL.** The fallback URL is used exactly as entered, whether the visitor arrives before activation, after expiration, or after the click limit is hit. If you need tracking on fallback traffic, add UTM parameters directly to the fallback URL.
</Note>


# Link preview
Source: https://docs.linkutm.com/links/link-preview

Override the social-share preview card title, description, image.

When someone pastes your short link into Slack, LinkedIn, WhatsApp, or similar apps, the platform fetches link preview tags to render a preview card. linkutm lets you override the preview title, description, and image per link without touching the destination page.

## When to use it

* Destination doesn't have preview tags (or has bad ones).
* You want a campaign-specific preview without changing the page.
* A/B testing share previews across channels.

## How to use it

<Steps>
  <Step title="Open Advanced → Social preview">
    In the link creation, expand **Advanced** and find the **Social preview** section.
  </Step>

  <Step title="Set preview fields">
    <ParamField>Card headline. Keep ≤60 chars.</ParamField>
    <ParamField>Subline. Keep ≤155 chars.</ParamField>
    <ParamField>Public image URL. Recommended 1200×630px PNG/JPG.</ParamField>
  </Step>
</Steps>

<Frame>
  <img alt="Link Preview modal - editable preview title and description fields with social card preview" />
</Frame>

## Real-world example

Same destination URL, different previews per channel:

```
Short:            go.acme.com/launch-li     (LinkedIn)
Preview title:    Acme Widget - built for engineering teams
Preview image:    https://cdn.acme.com/og/launch-linkedin.png

Short:            go.acme.com/launch-x      (X/Twitter)
Preview title:    Acme Widget. Now in beta.
Preview image:    https://cdn.acme.com/og/launch-twitter.png
```

Same destination `https://acme.com/launch`. Per-link preview settings drive different share cards.

## Common mistakes

<AccordionGroup>
  <Accordion title="Setting preview tags on the destination instead">
    If the destination already has correct preview tags, you don't need this. Override only when you want different cards per link.
  </Accordion>

  <Accordion title="Forgetting cache">
    LinkedIn and Meta cache preview data. Use their debug tools to flush after changes.
  </Accordion>

  <Accordion title="Image too large or non-public">
    Files over \~5 MB or URLs behind auth won't render. 1200×630 PNG/JPG, public.
  </Accordion>

  <Accordion title="Image address starts with http, not https">
    If your preview image address starts with `http` instead of `https`, some platforms block it from showing. Always use an `https` image address.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Imported links** auto-fetch preview data from the destination during import (5s timeout). If the fetch fails, the favicon falls back to Google's favicon service for the destination domain.
</Note>


# Password-protected links
Source: https://docs.linkutm.com/links/password-protected

Require a password before visitors are redirected to your destination URL.

When you set a password on a link, visitors who click it are shown a password entry page. They must enter the correct password to be redirected to the destination URL.

## How to use it

<Steps>
  <Step title="Open Advanced">
    In the create new link panel, click the **Advanced** button in the bottom bar.
  </Step>

  <Step title="Set a password">
    In the **Password Protection** field, type a password.
  </Step>

  <Step title="Save the link">
    The password is saved on the link.
  </Step>

  <Step title="Share the password">
    Send the password to your intended recipients through a separate channel.
  </Step>
</Steps>

<Frame>
  <img alt="Advanced settings panel - Password, Click Limit, Expiration date, and iOS/Android redirect fields" />
</Frame>

## Common mistakes

<AccordionGroup>
  <Accordion title="Reusing one password across many links">
    If one link leaks, all leak. Use a different password per link or per campaign.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Password and expiration.** Once a link passes its expiration date, it redirects to the fallback URL (or shows an error if none is set), regardless of any password stored on it.
</Note>


# QR codes
Source: https://docs.linkutm.com/links/qr-codes

Generate a QR for any link to use on print, packaging, or events.

Any short link in linkutm can be rendered as a QR code. The QR encodes the short URL - scanning it triggers the same redirect (and the same UTM tracking) as a click.

## When to use it

* Print: flyers, business cards, packaging.
* Events: trade-show booths, conference signage.
* TV / video overlays.
* Restaurants, retail - anywhere the audience holds a phone but can't type.

## How to use it

<Steps>
  <Step title="Find your link">
    Sidebar → **Links**.
  </Step>

  <Step title="Open QR Code">
    On the link row, click **More options**, then select **QR Code**. The panel opens with a live preview and customization tabs.
  </Step>

  <Step title="Customize and download">
    Adjust settings across the tabs. The preview updates in real time. Click **Save** or use the download button to export as PNG, SVG, or JPEG.
  </Step>
</Steps>

## Customization

The QR panel has six tabs. Each controls a different visual aspect of the code.

**Logo** — Place a logo or icon in the center. Upload an image, enter text, or pick a social media preset: linkutm, WhatsApp, Facebook, Instagram, Twitter/X, YouTube, LinkedIn, Telegram, or TikTok.

<Frame>
  <img alt="Logo tab — Upload, Text, and social media preset options for the QR center" />
</Frame>

**Frame** — Add a border around the QR. Choose from 11 frame styles or leave it frameless.

<Frame>
  <img alt="Frame tab — 11 frame border style options" />
</Frame>

**Dots** — Change the shape of the QR dot pattern. 11 styles available.

<Frame>
  <img alt="Dots tab — 11 dot pattern shape options for the QR body" />
</Frame>

**Corners** — Style the three corner markers. Set corner square shape (6 options) and corner dot shape (5 options) independently.

<Frame>
  <img alt="Corners tab — corner square styles and corner dot styles" />
</Frame>

**Colors** — Set foreground, corner, and background colors. Foreground supports solid, linear gradient, and radial gradient fills. Toggle corner color on to set it separately from the foreground.

<Frame>
  <img alt="Colors tab — foreground color picker with solid, linear, and radial modes; corner color toggle; background color picker" />
</Frame>

**Visibility** — Control quiet zone size, error correction level, and whether the dots behind the center logo are hidden.

<Frame>
  <img alt="Visible tab — quiet zone slider, error correction dropdown, hide dots behind logo toggle" />
</Frame>

## Real-world example

Coffee shop loyalty stamp card:

```
Destination:  https://acme-cafe.com/loyalty
utm_source:   in_store
utm_medium:   qr_code
utm_campaign: loyalty_v2
Custom slug:  cafe-loyalty
```

Print QR for `go.acme-cafe.com/cafe-loyalty` on every receipt. Analytics shows scans by region (which store), device (iOS vs Android), time of day.

## Common mistakes

<AccordionGroup>
  <Accordion title="QR encoding the destination directly">
    Bypasses linkutm - no click tracking, no UTM consistency. Always encode the **short URL**, not the long destination.
  </Accordion>

  <Accordion title="Editing the link after print">
    Changing the slug breaks every printed QR. Lock the slug before you commit to print.
  </Accordion>

  <Accordion title="Logo making the QR unscannable">
    A large or complex logo reduces scan reliability. Keep the logo small and set error correction to High. The scan reliability indicator in the panel turns red when the code is at risk.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Links with pixels enabled** show a brief loading page before the redirect. QR scans inside an in-app browser may show this page. Tracking accuracy is not affected.
</Note>


# Short links
Source: https://docs.linkutm.com/links/short-link

How short codes work, when to customize them, and what makes one valid.

The short code is the path after your short domain: `go.acme.com/{shortCode}`. linkutm stores one mapping per code; clicks on the code redirect to your full UTM-tagged destination URL.

## When to use it

* Always - every link gets a short code, auto-generated or custom.
* When the slug appears in print, on a podcast read, or anywhere a human reads it aloud.
* Skip customization for ads - auto-generated codes are fine and prevent typos.

## How to set one

<Tabs>
  <Tab title="Auto-generated">
    Leave the **Custom slug** field empty when creating a link. linkutm generates a short code automatically.

    <Frame>
      <img alt="Create Link modal - Short Link field showing auto-generated slug" />
    </Frame>
  </Tab>

  <Tab title="Custom slug">
    Type your slug in the **Custom slug** field. Allowed: lowercase letters, numbers, hyphens. Keep it short - 3-15 chars reads best.

    <Frame>
      <img alt="Create Link modal - Custom slug field with user-typed branded slug" />
    </Frame>
  </Tab>
</Tabs>

## Real-world example

| Use case             | Slug strategy         | Example                |
| -------------------- | --------------------- | ---------------------- |
| Paid ads             | Auto-generated        | `go.acme.com/k7m2qpz`  |
| Email newsletter CTA | Auto or themed        | `go.acme.com/may-deal` |
| Podcast read         | Memorable, brand-tied | `go.acme.com/acme-pod` |
| QR on print          | Short, no ambiguity   | `go.acme.com/menu`     |

## Common mistakes

<AccordionGroup>
  <Accordion title="Reusing a slug">
    Short codes are globally unique across linkutm. If the system says *"already exists"*, pick another - even if no one in your workspace uses it.
  </Accordion>

  <Accordion title="Long descriptive slugs">
    `q2-2025-product-launch-google-ads` defeats the purpose. Aim for ≤15 characters.
  </Accordion>

  <Accordion title="Special characters">
    Only `a-z`, `0-9`, `-` allowed. Underscores, slashes, periods get rejected.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Renaming an existing slug.** Edit the link → change **Short code**. The old slug stops working immediately. All historical clicks remain attached to the link's analytics.
</Note>

<Note>
  **System paths.** Slugs that collide with system paths (`api`, `health`, `docs`, `favicon.ico`) won't resolve through the redirect. Avoid these as custom slugs.
</Note>

<Note>
  **Archived links.** Archiving a link does not stop it from redirecting. The link continues to work normally. Archive is for organization only.
</Note>

<Note>
  **Expired links.** Once the expiration date passes, the link redirects to the fallback URL if one is set. Without a fallback URL, visitors see an error page.
</Note>


# UTM builder
Source: https://docs.linkutm.com/links/utm-builder

The five fields, what they mean, and how linkutm cleans them before saving.

The UTM section of the link builder. Five standard fields plus optional custom UTMs. Values are cleaned by your [workspace UTM rules](/utm-rules/overview) on save.

## When to use it

Every link. UTMs are how Google Analytics, Mixpanel, Amplitude, and most attribution tools tell campaigns apart.

## The five fields

<ParamField>
  Which initiative this belongs to.
  Examples: `q2-launch`, `black-friday-2025`, `weekly-digest`.
</ParamField>

<ParamField>
  Where the click came from. Treat as a "platform name."
  Examples: `google`, `facebook`, `newsletter`, `partner-blog`.
</ParamField>

<ParamField>
  How the click was delivered. The "channel type."
  Examples: `cpc`, `email`, `social`, `display`, `affiliate`.
</ParamField>

<ParamField>
  Optional. Paid search keyword or audience segment.
  Examples: `running-shoes`, `lookalike-us`.
</ParamField>

<ParamField>
  Optional. Differentiator for A/B variants or creative pieces.
  Examples: `headline-a`, `carousel-3`, `cta-orange`.
</ParamField>

<Frame>
  <img alt="UTM Parameters modal - Quick Apply Template dropdown with Source, Medium, Campaign, Term, Content fields and live preview of the final UTM string" />
</Frame>

## How it works

When you save a link, the entered values pass through your workspace's UTM Rules in this order:

<Steps>
  <Step title="Force lowercase">`Summer-Sale` → `summer-sale` (default ON).</Step>
  <Step title="Space replacement">`summer sale` → `summer_sale` using your configured space character (default `_`).</Step>
  <Step title="Max length">Truncated/rejected if over the workspace limit (default 100).</Step>
  <Step title="Prohibited terms">Hard fail if value contains any banned term you set ("test", "draft", etc).</Step>
  <Step title="Allowed characters">Hard fail if value contains characters outside the set you allow (lowercase, numbers, dots, hyphens). Skipped if you haven't restricted any.</Step>
</Steps>

The cleaned values are stored. See [UTM Rules](/utm-rules/overview) to configure each step.

## Custom UTM parameters

Beyond the five standards, you can attach additional custom parameters to a link. Add a name and value in the Custom UTM Parameters section, and they are appended to every redirect as extra URL parameters. For example, adding `audience` = `lookalike-3` appends `&utm_audience=lookalike-3` to the destination URL.

## Real-world examples

<Tabs>
  <Tab title="Google Ads">
    ```
    utm_source=google
    utm_medium=cpc
    utm_campaign=q2-launch
    utm_term={keyword}        ← Google Ads dynamic insertion
    utm_content=headline-a
    ```
  </Tab>

  <Tab title="Meta Ads">
    ```
    utm_source=facebook
    utm_medium=paid-social
    utm_campaign=q2-launch
    utm_content=video-carousel-v2
    ```
  </Tab>

  <Tab title="Email">
    ```
    utm_source=newsletter
    utm_medium=email
    utm_campaign=weekly-digest-2025-w19
    utm_content=hero-cta
    ```
  </Tab>

  <Tab title="Influencer / partner">
    ```
    utm_source=partner-jane-doe
    utm_medium=affiliate
    utm_campaign=q2-launch
    ```
  </Tab>
</Tabs>

## Common mistakes

<AccordionGroup>
  <Accordion title="Source vs medium swapped">
    `source=email, medium=newsletter` is wrong. Source = *platform name*; medium = *channel type*. Right: `source=newsletter, medium=email`.
  </Accordion>

  <Accordion title="Free-form campaign names">
    `Q2 Launch !!`, `q2 launch`, `Q2_Launch` become different rows in GA without rules. Use a [template](/utm-templates/overview) per campaign.
  </Accordion>

  <Accordion title="Using utm_term for non-search">
    `utm_term` is conventionally paid-search keyword. For audience segments use `utm_content` or a custom UTM.
  </Accordion>

  <Accordion title="PII in UTMs">
    UTMs land in your destination URL and analytics. Don't include emails, names, anything personally identifiable.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **UTMs already on the destination URL** are preserved. linkutm appends its UTMs alongside them; if there's a key collision, linkutm's value wins.
</Note>


# Projects (folders within workspaces)
Source: https://docs.linkutm.com/organization/managing-projects

Use separate folders as project containers when one workspace holds multiple initiatives.

linkutm doesn't have a separate "project" entity. The equivalent is a **separate folder inside a workspace**. Use one folder per campaign, brand, or client initiative when you don't need full data isolation.

Folders are flat. They don't support nesting, parent/child relationships, or linked folder structures.

## When to use folder-as-project

| Need                                               | Use             |
| -------------------------------------------------- | --------------- |
| Data isolation, separate billing, separate members | A new workspace |
| Logical grouping, shared team, shared domain       | A folder        |
| Per-campaign tracking                              | A folder        |
| Per-quarter rollup                                 | A folder        |

If multiple stakeholders need access but **shouldn't see each other's links**, use workspaces. If everyone on the team already sees everything, use folders.

## How to set up

<Steps>
  <Step title="Create separate folders for each project">
    Sidebar → **Folders & Tags** → **New Folder**. Examples: `Q2 Launch`, `Brand Refresh`, `Client: Globex`.
  </Step>

  <Step title="Create additional folders for channels if needed">
    If you want to separate channels, create each one as its own folder. For example: `Q2 Launch - Paid Search`, `Q2 Launch - Paid Social`, `Q2 Launch - Email`, `Q2 Launch - Organic`.
  </Step>

  <Step title="Set a default folder">
    Make the active project the **Default** folder. The link builder UI pre-selects it for new links unless you pick another.
  </Step>

  <Step title="Apply tags for cross-project attributes">
    `experiment`, `evergreen`, `paused` - cross-cuts every project. See [Folders & Tags](/links/folders-and-tags).
  </Step>
</Steps>

## Real-world example

Internal SaaS marketing team running three projects in one workspace:

```
Workspace: Acme Marketing

Folders:
- Q2 Product Launch
- Q2 Product Launch - Paid Search
- Q2 Product Launch - Paid Social
- Q2 Product Launch - Email
- Q2 Product Launch - PR
- Lifecycle Email
- Lifecycle Email - Onboarding
- Lifecycle Email - Retention
- Lifecycle Email - Win-back
- Always-On
- Always-On - Brand Search
- Always-On - Organic CTA
```

Tags: `experiment`, `paused`, `seasonal` - apply across folders.

## Common mistakes

<AccordionGroup>
  <Accordion title="Reaching for a new workspace when a folder fits">
    Workspaces are heavy: separate billing, separate domains, separate members. If you don't need isolation, use a folder.
  </Accordion>

  <Accordion title="Expecting nested folders">
    Folders are separate, flat containers. Use naming conventions or tags to represent channel, quarter, or status instead of nesting folders.
  </Accordion>

  <Accordion title="Project sprawl">
    Once a project ends, deactivate or delete its folder. Use **archive** on links if you want them out of default views but kept for analytics.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Default folder logic.** Only one default per workspace. Setting a new default unsets the old one automatically.
</Note>


# Managing workspaces
Source: https://docs.linkutm.com/organization/managing-workspaces

Create, rename, soft-delete, restore, or permanently delete a workspace.

Operations on a workspace: create, update name/slug/logo, switch between workspaces, soft-delete (trash), restore, permanent delete.

## How to create

<Steps>
  <Step title="Open workspace switcher">
    Top-left of the dashboard → **+ New workspace**.
  </Step>

  <Step title="Name + slug">
    Name is the display name. Slug must be lowercase letters, numbers, and hyphens; if you don't specify one, the system generates it from the name.
  </Step>

  <Step title="Done">
    You become the **owner**. The workspace gets the system default short domain attached automatically. UTM rules start at defaults.
  </Step>
</Steps>

<Frame>
  <img alt="Create new workspace modal - workspace name and slug fields" />
</Frame>

## How to update

<Steps>
  <Step title="Open workspace settings">
    Sidebar → **Settings** → **Workspace** (or `/{slug}/settings`).
  </Step>

  <Step title="Edit name, slug, logo">
    * Name: case-insensitive unique per owner.
    * Slug: must remain unique globally.
    * Logo: image upload.
  </Step>
</Steps>

## How to delete

Two-stage delete process for safety:

<Frame>
  <img alt="Delete workspace panel showing soft delete and permanent delete options" />
</Frame>

<Steps>
  <Step title="Soft delete (trash)">
    Settings → **Danger zone** → **Delete workspace**. Type `delete/{slug}` to confirm.

    The workspace moves to trash. Members get a notification email. **Workspace remains restorable for 7 days.**
  </Step>

  <Step title="Find and restore a soft-deleted workspace">
    The next time you log in, soft-deleted workspaces appear in the workspace selector as **Deactivated workspaces**. Select it and click **Restore**. Owner only. Workspace becomes active again, members regain access.
  </Step>

  <Step title="Permanent delete">
    After 7 days, the workspace is purged automatically. Or owner can hard-delete immediately by confirming again - owner email gets a final confirmation.

    All data is gone: links, click history, templates, domains, members. Cannot be recovered.
  </Step>
</Steps>

<Warning>
  Permanent delete is irreversible. Click history, custom domains (DNS records remain - you must reassign), member access, and billing history are removed. Export anything you need first.
</Warning>

## Real-world example

Closing out an agency client:

```text theme={null}
Day 0:    Soft-delete "Client: Soylent". Members get email.
Day 1-6:  Client requests final reports - restore, export, soft-delete again.
Day 7+:   Auto-purged. Custom domain (soy.link) becomes orphan; client takes it back via DNS.
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Confusing soft-delete with deactivate">
    Soft-delete blocks workspace use. There's no "pause" mode short of removing members and not creating new links.
  </Accordion>

  <Accordion title="Deleting a workspace with active subscriptions">
    Soft-delete doesn't cancel subscriptions automatically. Cancel billing first via the billing page.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Only the owner can delete.** Even an `admin` cannot delete the workspace or manage billing - those two are owner-only. `member` and `viewer` roles cannot delete either.
</Note>

<Note>
  **Soft-deleted workspace links still redirect**, until the 7-day purge. After purge, they stop working and show a "not found" page. If your custom domain is on the workspace, plan the cutover.
</Note>


# Workspaces & organization
Source: https://docs.linkutm.com/organization/overview

How linkutm structures multi-team, multi-client setups.

The mental model:

* **Account** - your user. Can belong to many workspaces.
* **Workspace** - the unit of isolation. All links, folders, tags, templates, UTM rules, custom domains, pixels, API keys, analytics, billing, and members live here.
* **Member** - a user attached to a workspace with a role (`owner`, `admin`, `member`, `viewer`).
* **Folders** - sub-organization *within* a workspace.

There's no concept of "organization" above workspace. Run multiple workspaces (e.g., per client, per brand) on one account.

## When to use multiple workspaces

<Tabs>
  <Tab title="Agency, multi-client">
    One workspace per client. Their links/domains/templates/billing isolated. Owner moves between workspaces from the workspace switcher.
  </Tab>

  <Tab title="Multi-brand company">
    One workspace per brand. Different custom domains per brand (`go.acme.com`, `pro.acme.link`).
  </Tab>

  <Tab title="Internal vs external">
    One workspace for marketing-public links, one for internal/dogfood links. Cleaner analytics, separate access control.
  </Tab>

  <Tab title="Don't multiply">
    Don't create a workspace per campaign or per quarter. Use [folders](/links/folders-and-tags) for that.
  </Tab>
</Tabs>

## Real-world example

Acme Marketing Agency:

```
Account: jane@acme-agency.com
Workspaces:
├── Acme Internal       (slug: acme-internal)        - owner: jane
├── Client: Globex      (slug: client-globex)        - owner: jane
├── Client: Initech     (slug: client-initech)       - owner: jane
└── Client: Soylent     (slug: client-soylent)       - owner: jane

Each workspace:
├── Members (with per-client account managers)
├── Domains (each client's branded short domain)
├── Templates (per-client UTM presets)
├── UTM Rules (per-client naming convention)
└── Plan & usage (billed per workspace)
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Workspace per campaign">
    Creates billing fragmentation and member-management overhead. Use folders.
  </Accordion>

  <Accordion title="Sharing one workspace across two clients">
    Defeats data isolation. Members of Client A can see Client B's links.
  </Accordion>

  <Accordion title="Confusing slug with name">
    Slug is the URL identifier (`acme-internal`). Name is the display name (`Acme Internal`). They're independent.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Workspace name unique per owner.** You can't own two workspaces with the same name (case-insensitive). Different owners can.
</Note>

<Note>
  **Slug uniqueness.** Slugs are globally unique across linkutm.
</Note>


# Agency client onboarding
Source: https://docs.linkutm.com/playbooks/agency-onboarding

How to set up a new client workspace in linkutm, configure their UTM convention, invite the client, and hand off a working link system in under an hour.

## When to use this playbook

You're an agency operator adding client number two, five, or fifteen. You need their UTM links isolated from other clients, their naming convention locked down before anyone starts building campaigns, and a clean handoff so the client can self-serve without breaking your attribution setup.

This playbook covers one client onboarding end to end.

***

## What you'll have when done

* A dedicated workspace for the client (isolated links, analytics, team members)
* A custom short domain on the client's brand (optional but recommended)
* A UTM naming convention locked in via Rules before the first link is created
* The client invited with the right permission level
* A template set for their top 5 channels, ready to use

***

## Step 1: Create the client workspace

<Steps>
  <Step title="Create a new workspace">
    Go to **Workspaces** in the sidebar → **New Workspace**. Name it after the client: `Acme Corp` not `Client 3`.

    One workspace per client. Never share a workspace across clients - links, analytics, domains, and rules are all workspace-scoped.
  </Step>

  <Step title="Set workspace defaults">
    Inside the new workspace, go to **Settings → General**:

    * Set the workspace name exactly as it will appear in reports
    * Set the default link expiry if the client uses campaign-specific links that should expire
  </Step>
</Steps>

<Note>
  Each workspace has its own UTM Rules, templates, custom domains, and team members. Switching workspaces in the sidebar is how you move between clients.
</Note>

***

## Step 2: Configure the client's custom domain (recommended)

Branded short links (`go.acmecorp.com/campaign-link`) look more professional than a shared domain and keep click data attributed to the client's brand.

<Steps>
  <Step title="Get the domain from the client">
    Ask the client to provide or create a subdomain they control: `go.clientdomain.com`, `links.clientdomain.com`, or `l.clientdomain.com` are common patterns. They need DNS access to add a CNAME record.
  </Step>

  <Step title="Add the domain in linkutm">
    Go to **Sidebar → Domains → Add Domain**. Enter the subdomain. linkutm will provide a CNAME target to give the client.
  </Step>

  <Step title="Client adds the CNAME record">
    The client logs into their DNS provider (Cloudflare, GoDaddy, Route 53, etc.) and adds:

    * Type: `CNAME`
    * Name: `go` (or whatever subdomain prefix they chose)
    * Value: the CNAME target linkutm provided

    DNS propagation takes 5 minutes to 48 hours depending on TTL.
  </Step>

  <Step title="Verify and set as default">
    Once propagated, the domain shows as **Active** in Sidebar → Domains. Set it as the default short domain for this workspace so all new links use it automatically.
  </Step>
</Steps>

***

## Step 3: Define and enforce the client's UTM convention

This is the most important step. Do it before the client or any team member creates a single link.

<Steps>
  <Step title="Agree on the naming convention">
    Walk through the [UTM naming convention](/playbooks/utm-naming-convention) with the client. Agree on:

    * Their approved `utm_source` values (which channels do they actually run?)
    * Their `utm_medium` values (match GA4 channel grouping rules)
    * Their `utm_campaign` pattern (`{quarter}-{theme}` is a sensible default)
    * Whether they need `utm_content` tracking (almost always yes for paid)
  </Step>

  <Step title="Configure UTM Rules for this workspace">
    Go to **Sidebar → UTM Rules** and turn on:

    * **Force lowercase**: prevents casing drift (`Google` vs `google`)
    * **Space character**: set to hyphen (`-`) to match the naming convention
    * **Prohibited values**: add test, draft, tbd, todo (blocks garbage values from polluting reports)

    Anyone creating a link with a prohibited term gets rejected on save, not after the campaign has already run.
  </Step>

  <Step title="Create templates for their top 5 channels">
    Go to **UTM Templates → Create Template** for each channel the client actively uses. At minimum:

    * Google Ads template
    * Meta Ads template
    * Newsletter/email template
    * LinkedIn template (if relevant)
    * Any affiliate or partner channel they use

    Leave `utm_content` blank in every template. That gets filled per link.

    See [Create a template](/utm-templates/create-template) for the full walkthrough.
  </Step>
</Steps>

***

## Step 4: Invite the client

<Steps>
  <Step title="Decide the permission level">
    | Role       | What they can do                                                                                        | Use for                                       |
    | ---------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
    | **Admin**  | Full workspace access (domain settings, UTM Rules, templates) except billing and deleting the workspace | Client's marketing lead or MOPs owner         |
    | **Member** | Create/edit links, use templates, view analytics                                                        | Day-to-day campaign managers                  |
    | **Viewer** | View links and analytics only                                                                           | Client stakeholders who need reporting access |

    Billing and workspace deletion stay with the **owner** (the person who created the workspace - your agency account). Recommend giving the client's MOPs lead Admin access on their own workspace. Don't give Admin to every campaign manager.
  </Step>

  <Step title="Send the invite">
    Go to **Settings → Team → Invite Member**. Enter their email and select the role. They'll receive an email to join the workspace.
  </Step>

  <Step title="Brief them on the convention">
    Share this doc with them: [UTM naming convention](/playbooks/utm-naming-convention). Tell them the Rules are already configured to enforce it. If they try to use an off-list source value, the save will fail with an error message explaining why.
  </Step>
</Steps>

***

## Step 5: Create the first campaign links together

Don't leave the client to figure it out alone. Walk them through creating one real campaign link during onboarding.

<Steps>
  <Step title="Pick a live campaign">
    Use a real campaign they're about to launch, not a test link. This ensures the convention is battle-tested before it matters.
  </Step>

  <Step title="Use the UTM builder with a template">
    Open **Links → Create Link → UTM Builder**. Select the appropriate channel template. Show them how the source and medium pre-fill and how to add the campaign name and content variant.
  </Step>

  <Step title="Show them the QR code and short link">
    If they run any offline or event marketing, show how to download the QR code from the link detail page. If they need the short link for a bio or print material, show how to copy it.
  </Step>

  <Step title="Confirm GA4 attribution">
    If they have GA4, have them click the link in a browser and check GA4 DebugView to confirm the UTM params are arriving correctly. See [GA4 integration](/integrations/ga4) for the verification steps.
  </Step>
</Steps>

***

## Handoff checklist

Before you consider onboarding complete:

* Workspace created and named correctly
* Custom domain active (or documented as deferred with a reason)
* UTM Rules configured and tested: try creating a link with a bad source value and confirm it rejects
* Templates created for all active channels
* Client team invited with correct roles
* Client's MOPs lead can log in and create a link independently
* GA4 attribution verified on at least one live link
* UTM naming convention page shared with the client team

***

## Common mistakes

<AccordionGroup>
  <Accordion title="Sharing one workspace across multiple clients">
    All links, analytics, rules, and team members are shared inside a workspace. One workspace per client is the only safe structure for agencies. Cross-client data leakage is a support relationship risk.
  </Accordion>

  <Accordion title="Setting up UTM Rules after links have been created">
    Rules validate new links on save. Existing links in the workspace are not retroactively validated or updated. Set up Rules before the first link. If the client already has links with inconsistent UTMs, treat those as legacy and start clean from the convention date.
  </Accordion>

  <Accordion title="Giving every client team member Admin access">
    Admins can change UTM Rules, delete templates, and modify the custom domain. Campaign managers don't need this. Give them Member access. Reserve Admin for the client's MOPs lead and your own agency account.
  </Accordion>

  <Accordion title="Skipping the custom domain step">
    Links on a shared domain look unprofessional in client reports and create ambiguity when the client eventually wants to migrate. Set up the custom domain at onboarding, even if it takes an extra day for DNS propagation.
  </Accordion>
</AccordionGroup>


# Pre-launch link audit
Source: https://docs.linkutm.com/playbooks/pre-launch-audit

A repeatable checklist for auditing campaign links before you hit send or go live, so bad UTMs don't make it into your analytics.

## When to use this playbook

You're about to launch a campaign: email send, paid media flight, event promotion, or product announcement. You have a set of links ready. This playbook is the 15-minute check you run before anything goes live to catch UTM errors, broken destinations, and attribution gaps before they become a data problem.

Run this for every campaign. The cost of finding a bad UTM before launch is 2 minutes. After launch it's a GA4 cleanup project.

***

## What you're checking

1. Every link has the correct UTMs (no missing fields, no off-convention values)
2. Destination URLs resolve and land on the right page
3. Short links are active and not expired
4. QR codes (if used) scan correctly
5. GA4 is reading the UTMs as expected on the destination page

***

## The audit checklist

### UTM completeness

For every link in the campaign:

* Links were built from workspace [UTM templates](/utm-templates/overview) where available - reduces manual entry and prevents drift
* `utm_source` is set and on the approved list (check [UTM naming convention](/playbooks/utm-naming-convention))
* `utm_medium` is set and maps to a valid GA4 channel group
* `utm_campaign` is set and matches the campaign name used across all channels
* `utm_content` is set if you're running more than one creative or placement variant
* `utm_term` is set for paid search links; empty for everything else
* No spaces, caps, or special characters in any value (linkutm Rules catch this on save, but verify)
* No PII in any UTM field

<Tip>
  In linkutm, open the link detail page. The UTM values are displayed in the Parameters panel. Check each one before copying the link.
</Tip>

### Campaign name consistency

* All links for this campaign share exactly the same `utm_campaign` value
* The campaign name matches what's in your campaign tracker or project management tool
* Google Ads, Meta, LinkedIn, email, and any other channels all use the same campaign slug

If a Google Ads link says `q2-pricing-launch` and the newsletter link says `q2-pricing`, you'll have a split campaign in GA4 and no single view of campaign performance.

### Destination URL check

For every link:

* Click the link manually in an incognito window and confirm it lands on the right page
* The destination page loads without errors (no 404, no redirect loop)
* The UTM parameters are visible in the browser address bar on the destination page
* If the destination page has a cookie consent banner, click through it and confirm GA4 still fires

<Warning>
  If your destination URL uses a redirect (e.g. a landing page platform that rewrites the URL), confirm the UTM parameters survive the redirect. Some platforms strip query strings. Test in an incognito window and check the final URL in the browser bar.
</Warning>

### Short link and expiry check

* Short link is active in linkutm (status shown on link detail page)
* If you set an expiry date, confirm it is after the campaign end date
* If the link is password-protected, confirm the password is what you intend and is documented

### QR code check (if applicable)

* Scan the QR code with a phone (not the phone's camera preview, actually follow through to the page)
* Confirm it resolves to the right destination with UTMs intact
* If the QR code is going to print, test the printed version at print size (small QR codes at low DPI often fail to scan)

***

## GA4 verification

Run this for at least one link per channel before the campaign goes live.

<Steps>
  <Step title="Open GA4 DebugView">
    In GA4 Admin → DebugView. Keep it open in a separate tab.
  </Step>

  <Step title="Click the linkutm link in an incognito window">
    Use incognito so you don't contaminate the session with your regular browsing history.
  </Step>

  <Step title="Check session_start in DebugView">
    Look for the `session_start` event in DebugView. Expand it and confirm:

    * `traffic_source.source` = your `utm_source`
    * `traffic_source.medium` = your `utm_medium`
    * `traffic_source.campaign` = your `utm_campaign`
  </Step>

  <Step title="Confirm channel grouping">
    In GA4 Reports → Traffic Acquisition, the session should appear in the correct default channel within a few minutes. If it shows as "Unassigned," your `utm_medium` value doesn't match GA4's channel rules. Fix it before launch.
  </Step>
</Steps>

See [GA4 integration](/integrations/ga4) for the full troubleshooting guide if attribution isn't showing correctly.

***

## Common failures and fixes

<AccordionGroup>
  <Accordion title="UTM params missing from destination URL">
    The most common cause: the destination URL was pasted into a system that stripped query strings (some email platforms, CMS redirect rules, or landing page builders do this). Test the full redirect chain in an incognito window. If params are stripped, configure the destination system to pass through query strings, or switch the link destination to a URL that doesn't redirect.
  </Accordion>

  <Accordion title="Campaign shows as two rows in GA4 because of inconsistent campaign names">
    Find the inconsistency before launch by listing all campaign links and comparing `utm_campaign` values. Use linkutm's link list filtered by campaign name to catch variants. Fix the outlier link before the campaign sends.
  </Accordion>

  <Accordion title="Short link returns 404 after redirect">
    The destination URL in the link record is wrong or the destination page was taken down. Open the link in linkutm, check the destination URL, update it if needed. Short links can be edited at any time and the update takes effect immediately.
  </Accordion>

  <Accordion title="GA4 shows Direct instead of the campaign source">
    Three causes: UTMs stripped in redirect (see above), GA4 tag blocked by ad blocker or cookie consent not accepted, or the destination page does not have the GA4 tag installed. Verify tag is present in browser dev tools → Network → filter for `google-analytics` or `gtag`.
  </Accordion>
</AccordionGroup>

***

## Audit log

Keep a record that the audit was completed. A one-line entry in your campaign tracker is enough:

```
2026-05-19 | Q2 pricing relaunch | 12 links | Pre-launch audit: PASS | Auditor: [name]
```

If a UTM issue surfaces post-launch, the audit log tells you whether it was a setup error (audit passed, something changed) or a process error (audit was skipped).


# UTM naming convention
Source: https://docs.linkutm.com/playbooks/utm-naming-convention

An opinionated, copy-paste-ready standard for utm_source, utm_medium, utm_campaign, utm_content, and utm_term so every link in GA4 lands in the right row.

## Why this matters

Every marketer on your team types UTMs differently. `Newsletter` vs `newsletter` vs `news_letter` creates three separate rows in GA4. Six months later, your channel attribution is split across dozens of near-duplicate source/medium combos and no one can tell you what drove pipeline last quarter.

A naming convention costs 30 minutes to set up. The cleanup it prevents costs weeks.

<Note>
  This is an opinionated default. Pick the parts that fit your team, enforce them with [UTM Rules](/utm-rules/overview), and update the vocab list quarterly. A convention that gets followed beats a perfect one that doesn't.
</Note>

***

## The format

```
utm_source   = {channel}
utm_medium   = {traffic-type}
utm_campaign = {quarter}-{theme}
utm_content  = {creative-variant}
utm_term     = {paid-keyword}          ← paid search only
```

**Rules that apply everywhere:**

* Lowercase only: `google` not `Google`
* Hyphens between words: `q2-launch` not `q2_launch` not `Q2 Launch`
* No spaces, no slashes, no special characters
* No dates inside `utm_campaign` (the date is in your analytics tool, not your UTM)
* No PII: no email addresses, user IDs, or names

***

## Parameter guide

### utm\_source: where the traffic came from

Use the **platform name**, lowercase, hyphen-separated. Lock this to a fixed vocab list.

| Value            | Use for                                        |
| ---------------- | ---------------------------------------------- |
| `google`         | Google Ads, Google Shopping                    |
| `meta`           | Facebook Ads, Instagram Ads                    |
| `linkedin`       | LinkedIn Ads                                   |
| `tiktok`         | TikTok Ads                                     |
| `x`              | X (Twitter) Ads                                |
| `newsletter`     | Your own email sends                           |
| `youtube`        | YouTube Ads or organic video                   |
| `podcast`        | Podcast sponsorships                           |
| `affiliate`      | Affiliate/referral partners                    |
| `partner-{name}` | Named partnerships, e.g. `partner-hubspot`     |
| `direct`         | QR codes, offline, vanity URLs                 |
| `organic-social` | Non-paid social posts (Instagram, LinkedIn, X) |

<Warning>
  Don't use `email` as a source. It's ambiguous. Is it your newsletter, a cold outreach sequence, or a transactional send? Use `newsletter`, `outbound`, or `transactional` instead.
</Warning>

**Enforce it:** Configure [UTM Rules](/utm-rules/overview) to block values outside your approved list. Anyone using an off-list value gets a rejection on save, not a messy row in GA4 three weeks later.

***

### utm\_medium: what kind of traffic

Medium = the marketing mechanism, not the platform.

| Value            | Use for                                    |
| ---------------- | ------------------------------------------ |
| `cpc`            | Cost-per-click paid search (Google, Bing)  |
| `paid-social`    | Any paid social placement                  |
| `email`          | All email: newsletter, nurture, outbound   |
| `display`        | Banner/programmatic display                |
| `video`          | Pre-roll, connected TV, YouTube TrueView   |
| `affiliate`      | Revenue-share or performance partner links |
| `organic-social` | Non-paid social posts                      |
| `podcast`        | Audio sponsorship read                     |
| `qr`             | QR codes (physical → digital)              |
| `referral`       | Inbound from other sites (unpaid)          |

<Note>
  GA4 uses `medium` to populate the **Default channel grouping** report. Stick to these values and your channels will auto-group correctly. Invent your own and they fall into "Unassigned."
</Note>

***

### utm\_campaign: what campaign this link belongs to

Pattern: **`{quarter}-{theme}`**

```
q1-brand-search
q2-pricing-relaunch
q3-enterprise-outbound
q4-black-friday
evergreen-free-trial
```

Rules:

* Always start with the quarter (`q1` / `q2` / `q3` / `q4`) or `evergreen` for always-on
* Theme is 1-3 words, hyphen-separated, describing the campaign's purpose
* No year in the value; your analytics date filter handles that
* Same campaign name across all channels that belong to one campaign

<Tip>
  If your Google Ads and your newsletter and your LinkedIn post are all promoting the same Q2 pricing page, they should all share `utm_campaign=q2-pricing-relaunch`. That's how you see cross-channel campaign performance in one row.
</Tip>

***

### utm\_content: which creative or placement

Use `utm_content` to tell variants apart within a campaign + channel combo.

Common patterns:

| Pattern                  | Example                          | Use for                       |
| ------------------------ | -------------------------------- | ----------------------------- |
| `{creative-name}`        | `hero-cta-blue`                  | A/B ad creative variants      |
| `{placement}`            | `sidebar` `footer` `inline`      | Placement within a page/email |
| `{subject-line-variant}` | `subject-a` `subject-b`          | Email subject line tests      |
| `{cta-copy}`             | `start-free-trial` `see-pricing` | CTA copy variants             |
| `{format}`               | `video` `static` `carousel`      | Ad format                     |

Leave `utm_content` **blank in templates**; fill it per link. If you bake it into a template, every link inherits the same content value and the variant data is useless.

***

### utm\_term: paid search keywords only

`utm_term` = the keyword that triggered the ad. Used almost exclusively for paid search.

```
utm_term=utm+tracking+tool
utm_term=link+shortener+for+marketing
utm_term=bitly+alternative
```

If you're not running paid search: leave it empty. Don't repurpose `utm_term` for audience segments or targeting notes; that data belongs in your ad platform, not your UTM.

***

## Channel cheatsheet

Copy-paste starting points per channel. Fill `utm_campaign` and `utm_content` per link.

<Tabs>
  <Tab title="Google Ads">
    ```
    utm_source=google
    utm_medium=cpc
    utm_campaign=q2-brand-search
    utm_content=headline-a
    utm_term={keyword}
    ```

    Use `{keyword}` as a literal ValueTrack parameter in Google Ads; it auto-populates the triggering keyword.
  </Tab>

  <Tab title="Meta Ads">
    ```
    utm_source=meta
    utm_medium=paid-social
    utm_campaign=q2-retargeting
    utm_content=carousel-pricing
    ```

    Meta auto-populates `utm_content` if you use `{{ad.name}}` in the URL parameter field, but stick to your own naming pattern for consistency across platforms.
  </Tab>

  <Tab title="LinkedIn Ads">
    ```
    utm_source=linkedin
    utm_medium=paid-social
    utm_campaign=q2-enterprise-demand
    utm_content=cta-book-demo
    ```

    LinkedIn's `{{CAMPAIGN_NAME}}` macro inserts the campaign name. Override it with your standard pattern instead of letting LinkedIn name it.
  </Tab>

  <Tab title="Newsletter / Email">
    ```
    utm_source=newsletter
    utm_medium=email
    utm_campaign=q2-product-update
    utm_content=hero-cta
    ```

    Every link in a single email send should share the same `utm_campaign`. Use `utm_content` to tell the hero CTA from the footer link from the inline text link apart.
  </Tab>

  <Tab title="Organic Social">
    ```
    utm_source=organic-social
    utm_medium=organic-social
    utm_campaign=evergreen-product-awareness
    utm_content=linkedin-post-may-19
    ```

    Source and medium are the same here; that's intentional and how GA4 groups organic social correctly. Use `utm_content` to identify the specific post.
  </Tab>

  <Tab title="Affiliate / Partner">
    ```
    utm_source=partner-hubspot
    utm_medium=affiliate
    utm_campaign=evergreen-integration-promo
    utm_content=blog-inline
    ```

    Name the partner in `utm_source` using the `partner-{name}` pattern. That way you can filter GA4 by source to see partner-by-partner performance without needing a separate dimension.
  </Tab>

  <Tab title="QR Codes / Offline">
    ```
    utm_source=direct
    utm_medium=qr
    utm_campaign=q2-event-booth
    utm_content=conference-badge
    ```

    QR codes generated in linkutm carry the short link + these UTMs. Attendees scanning the badge → `source=direct / medium=qr` in GA4.
  </Tab>
</Tabs>

***

## Bad to good examples

| Before                                | Problem                                 | After                                    |
| ------------------------------------- | --------------------------------------- | ---------------------------------------- |
| `utm_source=Email`                    | Caps → splits from `email` in GA4       | `utm_source=newsletter`                  |
| `utm_source=email`                    | Ambiguous. Which email type?            | `utm_source=newsletter`                  |
| `utm_medium=Social Media`             | Spaces + caps                           | `utm_medium=paid-social`                 |
| `utm_campaign=Q2 2025 Campaign`       | Spaces, caps, year                      | `utm_campaign=q2-brand-awareness`        |
| `utm_campaign=newsletter_may_19_2025` | Date baked in, will duplicate each week | `utm_campaign=q2-weekly-digest`          |
| `utm_content=` *(empty)*              | No way to tell creative variants apart  | `utm_content=hero-cta`                   |
| `utm_term=linkedin`                   | Term field used for channel             | Delete; that's what source/medium is for |
| `utm_source=FB`                       | Abbreviation, won't match `meta` filter | `utm_source=meta`                        |
| `utm_campaign=test`                   | Will pollute prod data, no meaning      | Block with UTM Rules prohibited values   |

***

## Enforce it with UTM Rules

Setting this convention once doesn't help if someone ignores it two weeks later. Pair this playbook with [UTM Rules](/utm-rules/overview) to make the convention self-enforcing.

**Minimum ruleset to configure:**

<Steps>
  <Step title="Force lowercase and hyphens">
    Turn on **Force lowercase** and set **Space character** to hyphen (`-`). This catches 80% of drift automatically. No more `Google` vs `google` or `Q2 Launch` vs `q2-launch`.
  </Step>

  <Step title="Block test and draft values">
    Under **Prohibited values**, add: test, draft, tbd, todo. Prevents test links from leaking into production data and polluting your reports.
  </Step>

  <Step title="Set your allowed characters (optional)">
    Under **Allowed characters**, select lowercase, numbers, and hyphens. Rejects anything with special characters or accidental spaces that slipped through.
  </Step>
</Steps>

***

## Governance

A naming convention rots if no one owns it. Assign these before you ship.

| Role                                     | Responsibility                                                                        | Cadence                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
| **Convention owner** (usually MOPs lead) | Approves new source/medium values, updates UTM Rules allowed lists, resolves disputes | On-demand + quarterly review |
| **All link creators**                    | Use linkutm templates for every new link; never hand-type UTMs                        | Per link                     |
| **Analytics owner**                      | Flags new GA4 "Unassigned" rows as signal that convention has drifted                 | Weekly                       |

**Adding a new source or medium:**

1. Convention owner approves the new value
2. Update UTM Rules with the new approved value
3. Create a new template for the channel (see [Create a template](/utm-templates/create-template))
4. Update this playbook

Don't let individuals add new values ad hoc. One rogue `utm_source=IG` takes one week to create and six months to clean up.

***

## Quick-start checklist

<Steps>
  <Step title="Copy the allowed source and medium lists above">
    Edit them to match your actual channels. Delete any you don't use.
  </Step>

  <Step title="Configure UTM Rules">
    Minimum: force lowercase on, hyphen as space character, blocked values: test/draft/tbd.
  </Step>

  <Step title="Create templates for your top 5 channels">
    Newsletter, Google Ads, Meta, LinkedIn, and your highest-volume partner. See [Create a template](/utm-templates/create-template).
  </Step>

  <Step title="Run your existing links through the audit">
    Filter GA4 → Source/Medium report → look for rows with caps, spaces, or off-list values. Those are your cleanup targets.
  </Step>

  <Step title="Share this page with the team">
    Bookmark it. Link to it in your team wiki. This is the source of truth, not a Notion doc only you can find.
  </Step>
</Steps>


# Team collaboration
Source: https://docs.linkutm.com/team-collaboration/overview

Invite members, assign roles, configure notifications.

You can invite anyone to your workspace. Each person gets a role that controls what they can view and edit. Members manage their own notification preferences per workspace and can be removed at any time by the owner.

## Roles

| Role       | What they can do                                                                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Owner**  | Full access to everything, including billing and deleting the workspace. The person who created the workspace. Cannot be removed or have their role changed. |
| **Admin**  | Full access except billing and deleting the workspace. Everything else an owner can do.                                                                      |
| **Member** | Default role when invited. Can create and edit links, manage folders, tags, and templates.                                                                   |
| **Viewer** | Read-only access. Can view links and analytics but cannot create or edit.                                                                                    |

## How to invite

<Steps>
  <Step title="Open Members">
    Sidebar → **Settings** → **Members** (or **Team**).
  </Step>

  <Step title="Send invite">
    Enter their email and select a role. The invite is sent by email and expires after 7 days.

    <Warning>
      The invite is tied to the email it was sent to. The person must sign in with that exact email address to accept it.
    </Warning>
  </Step>

  <Step title="Manage pending invites">
    Resend to reset the 7-day expiry, or cancel to remove the invite.
  </Step>
</Steps>

<Frame>
  <img alt="Team Members page - invite form, member list with roles (Owner/Admin/Member/Viewer), and Roles and Permissions table" />
</Frame>

## How to accept an invite

The invitee clicks the link in the email. They sign in (or create an account with the same email) and confirm.

## Removing members

<Steps>
  <Step title="Open Members and find the member">
    The owner and admin can remove any member except themselves.
  </Step>

  <Step title="Confirm">
    The member loses access immediately. Links they created stay in the workspace.
  </Step>
</Steps>

## Per-member notifications

Each member controls what triggers an email notification for them:

| Notification     | When you get it                                                     |
| ---------------- | ------------------------------------------------------------------- |
| New link created | A teammate creates a link in this workspace                         |
| Click milestones | Your link hits 100, 500, 1k, 5k, 10k, 50k, 100k, 500k, or 1M clicks |
| Team changes     | A member joins, leaves, or has their role changed                   |
| Weekly report    | Weekly digest of workspace activity                                 |

<Frame>
  <img alt="Notification settings - Short links, Link alerts, and Team members sections each with ON/OFF toggles per event type" />
</Frame>

## Account-level notifications

Under **Account → Notifications**, each user has separate settings for system-wide events: domain updates, link expiry, billing alerts, and security alerts.

## Real-world example

Agency client team:

```text theme={null}
Workspace: Client: Globex
Members:
- jane@acme-agency.com  - owner   (account manager)
- kim@acme-agency.com   - member  (campaign analyst)
- nick@acme-agency.com  - member  (designer)
```

Jane gets all notifications. Kim gets click milestones and weekly report. Nick disables everything except weekly report.

## Common mistakes

<AccordionGroup>
  <Accordion title="Inviting beyond the member limit">
    Each workspace has a maximum number of members. New invites are blocked once the workspace is at capacity.
  </Accordion>

  <Accordion title="Re-inviting an existing member">
    You cannot invite someone who is already a member. Change their role directly from the Members page instead.
  </Accordion>

  <Accordion title="Trying to remove the owner">
    The owner cannot be removed from their own workspace.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Invite expiry.** Invites expire after 7 days. Resend the invite from the Members page to generate a new one.
</Note>

<Note>
  **Email matching.** Invites match the exact email address sent. If the person signs in with a different address, the invite will not connect.
</Note>

<Note>
  **Lowering the member limit.** If a workspace's member limit drops below the current count, existing members keep access. The new limit only blocks new invites until headcount comes down.
</Note>


# UTM Parameter library
Source: https://docs.linkutm.com/utm-parameters/overview

The workspace dictionary of allowed UTM values. Powers autocomplete and consistency.

## What are UTMs?

UTMs (Urchin Tracking Modules) are short tags you add to the end of any URL so your analytics tool can tell you exactly where each visitor came from. Without them, GA4 and other tools report most traffic as "Direct," which means the origin is unknown.

A UTM-tagged link looks like this:

```
https://yoursite.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=q2-launch
```

When someone clicks it, GA4 reads those tags and records: this session came from `newsletter`, via `email`, for campaign `q2-launch`. You can then compare newsletter vs Google Ads vs LinkedIn in one report, for the same campaign.

The five standard parameters are: `utm_source` (platform), `utm_medium` (channel type), `utm_campaign` (campaign name), `utm_content` (creative variant), and `utm_term` (paid keyword). The first three are the ones that matter most.

***

The Parameter library is your workspace's hierarchical dictionary of UTM values:

* **Parents**: the five standard fields - `source`, `medium`, `campaign`, `term`, `content`.
* **Children**: the allowed values under each parent - e.g., under `source`: `google`, `facebook`, `newsletter`, etc.

The link builder's autocomplete pulls from this library.

## When to use it

* You want autocomplete suggestions when team members fill UTMs.
* You want a canonical list of acceptable values that everyone sees.
* You're enforcing values via UTM Rules.

The five parents (`source`/`medium`/`campaign`/`term`/`content`) are built-in and can't be deleted. Only their display name and tooltip can be edited. All child values are fully editable. Common values are pre-loaded when your workspace is created.

## How to manage it

<Steps>
  <Step title="Open the library">
    Sidebar → **UTM Parameters**. Tree view: parents on top, children nested.
  </Step>

  <Step title="Add a value">
    Click a parent (e.g., `source`) → **Add value**. Required: `name` (display) + `code` (lowercase identifier, becomes the actual UTM value). Optional: `tooltip`, `description`.
  </Step>

  <Step title="Edit / reorder / delete">
    * Edit name and metadata anytime.
    * Delete only if no children depend on it.
  </Step>
</Steps>

<Frame>
  <img alt="UTM Parameters page - five system parameters on the left, Source values list on the right (Google, Facebook, Twitter, LinkedIn, and more)" />
</Frame>

## Real-world example

A B2B SaaS company customizes the library:

```
source/
├── google
├── linkedin
├── product_hunt
├── partner_capterra
├── partner_g2
└── newsletter

medium/
├── cpc
├── paid_social
├── email
├── content_partnership   ← custom
└── webinar               ← custom
```

The autocomplete now reflects how this team actually drives traffic - partner sites, content partnerships, webinars - not generic SaaS defaults.

## Common mistakes

<AccordionGroup>
  <Accordion title="Mixed-case codes">
    Codes are forced lowercase on insert. `Newsletter` becomes `newsletter`. Don't try to maintain casing here.
  </Accordion>

  <Accordion title="Duplicate codes">
    Codes are unique per workspace. If you try to add a value that already exists (e.g., `google` when it's already there), the save will fail. Check the existing list first.
  </Accordion>

  <Accordion title="Deleting a parent with children">
    You can't delete a parent parameter (like `source`) while it still has child values under it. Delete the child values first, then the parent.
  </Accordion>

  <Accordion title="Treating library as the enforcer">
    Library powers autocomplete. It suggests values but doesn't block anything. To enforce naming standards, configure [UTM Rules](/utm-rules/overview) with prohibited values and character restrictions.
  </Accordion>
</AccordionGroup>


# UTM rules
Source: https://docs.linkutm.com/utm-rules/overview

Workspace-wide validation and standardization that runs on every link save.

<Tip>
  Setting up UTM Rules for the first time? Start with the [UTM naming convention](/playbooks/utm-naming-convention) playbook to define your approved source, medium, and campaign values before configuring the rules engine.
</Tip>

UTM Rules is a set of rules that runs whenever a link is created or updated. One rule set per workspace. It applies in this order:

1. **Force lowercase** (default ON) - `Summer_Sale` → `summer_sale`
2. **Space replacement** (default `_`) - `summer sale` → `summer_sale`
3. **Max length** (default 100) - reject values longer than this
4. **Prohibited values** - fail if value contains any banned term
5. **Allowed characters** - fail if value contains characters outside the selected set (lowercase, numbers, dots, hyphens)

## When to use it

* Marketing team of more than one person - drift is guaranteed without rules.
* Anyone publishing UTMs to a shared analytics tool (GA, Mixpanel) where casing/typos create duplicate rows.
* Agencies enforcing client-specific naming conventions.

## How to configure

<Steps>
  <Step title="Open the rules page">
    Sidebar → **UTM Rules**.
  </Step>

  <Step title="Set the basics">
    <Frame>
      <img alt="Space Character dropdown - Underscore selected, with Hyphen, Plus, URL Encoded, and Remove spaces options each showing a live preview" />
    </Frame>
  </Step>

  <Step title="Set the basics">
    <Frame>
      <img alt="Space Character dropdown - Underscore selected, with Hyphen, Plus, URL Encoded, and Remove spaces options each showing a live preview" />
    </Frame>
  </Step>

  <Step title="Save and test">
    Try creating a link with bad values. Validation errors appear inline on the failing fields.
  </Step>
</Steps>

<Frame>
  <img alt="UTM Rules page - Space Character, Force Lowercase toggle, Max Length, Allowed Characters checkboxes (lowercase, numbers, dots, hyphens), and Prohibited Values settings" />
</Frame>

## Real-world example

<Tabs>
  <Tab title="Force consistency">
    ```text theme={null}
    forceLowercase: true
    spaceCharacter: "_"
    allowedCharactersRegex: "^[a-z0-9_-]+$"
    prohibitedValues: ["test", "draft", "tbd"]
    ```

    No more `Summer Sale!` slipping into prod.
  </Tab>

  <Tab title="Require campaign">
    ```text theme={null}
    Required field rule:
    {
      validationType: "not_empty",
      requiredParameters: ["campaign"],
      description: "Campaign name is required"
    }
    ```

    Every link must have `utm_campaign`.
  </Tab>

  <Tab title="Allow only known sources">
    ```text theme={null}
    Required field rule:
    {
      validationType: "allowed_values",
      requiredParameters: ["source"],
      allowedValues: ["google", "facebook", "linkedin", "newsletter"]
    }
    ```

    Anything outside the list fails.
  </Tab>

  <Tab title="Auto-fill medium">
    ```text theme={null}
    Conditional logic rule:
    if ifField=source, condition=equals, ifValue=google
    then set thenSet=medium, toValue=cpc
    ```

    Anyone picking `source=google` gets `medium=cpc` automatically.
  </Tab>
</Tabs>

**Force consistency across the whole team:**

* **Force lowercase**: on
* **Space character**: hyphen
* **Allowed characters**: select lowercase, numbers, dots, hyphens
* **Blocked values**: test, draft, tbd

No more `Summer Sale!` slipping into prod.

## Edge cases

<Note>
  **Rules cleaning vs validation.** Steps 1-2 (lowercase, space replacement) **transform** values silently. Steps 3-5 (length, prohibited, allowed characters) **reject** the save with errors.
</Note>

<Note>
  **Default rules ship per workspace.** Every new workspace starts with force lowercase on, underscore for spaces, and a 100-character max length automatically. They CAN be turned off using the toggle given in the UTM rules panel but it is ON by default.
</Note>


# Create a template
Source: https://docs.linkutm.com/utm-templates/create-template

Save a UTM preset for a channel or campaign type.

Saving a named set of UTM values that can be applied to new links with one click.

## When to use it

You're about to type the same `utm_source` / `utm_medium` combination for the third time. Stop. Make a template.

## How to create one

<Steps>
  <Step title="Open Templates">
    Sidebar → **UTM Templates** → **Create Template**.
  </Step>

  <Step title="Name and Description(optional) ">
    Name shows in the template picker. Description is internal context - when to use this template.
  </Step>

  <Step title="Fill the UTM fields">
    Set the fields you want pre-filled. Leave any field blank if it's not common to the use case.

    | Field          | Set if                                   | Leave blank if               |
    | -------------- | ---------------------------------------- | ---------------------------- |
    | `utm_source`   | Always                                   | (always set)                 |
    | `utm_medium`   | Always                                   | (always set)                 |
    | `utm_campaign` | One template per recurring campaign      | Per-link campaigns           |
    | `utm_term`     | Paid search with stable keyword strategy | Otherwise                    |
    | `utm_content`  | Same creative across all links           | Different creatives per link |
  </Step>

  <Step title="Save">
    Template is immediately available in the link builder's template picker.
  </Step>
</Steps>

<Frame>
  <img alt="Create Template modal - Template Name, Campaign, Description, Source, Medium, Term, Content fields" />
</Frame>

## Real-world example

Newsletter template - kept loose so one template covers all newsletters:

```
Name:         Newsletter - generic
Description:  Default for any weekly/monthly newsletter send
utm_source:   newsletter
utm_medium:   email
utm_campaign: (blank - set per send)
utm_term:     (blank)
utm_content:  (blank - set per CTA)
```

Per-link, the marketer fills `utm_campaign=weekly_digest_2025_w19` and `utm_content=hero_cta`.

## Common mistakes

<AccordionGroup>
  <Accordion title="Over-specific templates">
    `Newsletter - Week 19 - Hero CTA` becomes a single-use template. Make it generic; vary at link time.
  </Accordion>

  <Accordion title="Inconsistent naming">
    `News - Email`, `Email/Newsletter`, `newsletter_email` all describe the same thing. Settle on a convention before the team builds 30 templates.
  </Accordion>

  <Accordion title="Skipping the description field">
    Six months in, "Q2 Launch - paid" is ambiguous. Describe **when** to use this template, not just what it sets.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Templates don't enforce.** A user can apply a template, then change every field. To enforce, use [UTM Rules](/utm-rules/overview) (required-field, allowed-values, conditional logic).
</Note>

<Note>
  **Editing a template doesn't update past links.** Past links keep the values they had at save-time. Future links using the template get the new values.
</Note>


# Manage templates
Source: https://docs.linkutm.com/utm-templates/manage-templates

Edit, sort, and audit usage of your templates.

The Templates page shows all workspace templates with usage counts, status, and edit/delete actions.

## When to use it

* Quarterly cleanup of unused templates.
* Auditing which channels actually drive volume.
* Renaming templates after a brand/strategy shift.

## How to manage them

<Steps>
  <Step title="List view">
    Sidebar → **UTM Templates**. Default sort: active templates first, then most-recently-created.
  </Step>

  <Step title="Search">
    Search matches name, description, source, medium, campaign - useful when you have 50+ templates.
  </Step>

  <Step title="See usage">
    Each template shows the usage count - how many times it's been applied to a link. Templates with 0 uses after a month are candidates for cleanup.
  </Step>

  <Step title="Edit">
    Click any template → **Edit**. Update name, description, or any UTM field. Past links unaffected.
  </Step>

  <Step title="Delete">
    **Delete**: permanent. Past links keep their values, but the template is gone.
  </Step>
</Steps>

<Frame>
  <img alt="UTM Templates - template row with Edit, Duplicate, and Delete action buttons visible" />
</Frame>

## Real-world example

Quarterly audit of an agency workspace:

| Template             | Uses | Action                    |
| -------------------- | ---- | ------------------------- |
| Google Brand Search  | 412  | Keep                      |
| Newsletter - generic | 287  | Keep                      |
| Test - Don't Use     | 0    | Delete                    |
| Old Logo Refresh     | 6    | Delete (retired strategy) |

## Common mistakes

<AccordionGroup>
  <Accordion title="Editing a template assuming retroactive changes">
    Past links keep their original values. Edits affect future applications only.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  Use the *Most-used templates* section on the UTM Templates page to identify high-leverage templates worth refining.
</Note>


# Templates overview
Source: https://docs.linkutm.com/utm-templates/overview

Save UTM presets so the team stops re-typing source/medium for every link.

<Tip>
  Before creating templates, agree on your team's naming convention. The [UTM naming convention](/playbooks/utm-naming-convention) playbook defines the approved source, medium, and campaign values your templates should use.
</Tip>

A UTM template is a saved set of UTM values (source, medium, campaign, term, content) you can apply with one click in the link builder. Workspace-scoped. Track how often each is used.

<Frame>
  <img alt="UTM Templates page - template cards showing source, medium, campaign tags and usage counts" />
</Frame>

## When to use it

* Same channel, repeat campaigns: weekly newsletter, monthly Google Ads, recurring event.
* Multi-person team - without templates, three marketers will spell `Newsletter`/`newsletter`/`news_letter` differently.
* Big launches with 20+ links per channel.

If you only build a one-off link a quarter, skip templates. Use [UTM Rules](/utm-rules/overview) instead - they apply automatically to all links.

## How it works

A template stores the raw UTM values. When applied during link creation, they pre-fill the form. You can override any field before saving.

The system tracks how many times each template has been used - see [Manage templates](/utm-templates/manage-templates) for the most-used view.

## Real-world example

A SaaS company runs:

| Template            | source       | medium        | campaign         |
| ------------------- | ------------ | ------------- | ---------------- |
| Newsletter Weekly   | `newsletter` | `email`       | `weekly-digest`  |
| Google Brand Search | `google`     | `cpc`         | `brand-search`   |
| Meta Retargeting    | `facebook`   | `paid-social` | `retargeting-v2` |
| LinkedIn Webinar    | `linkedin`   | `paid-social` | `webinar-q2`     |

Marketer building this week's newsletter link: pick **Newsletter Weekly** template → fill destination URL + content (`hero_cta`) → done in 5 seconds.

## Common mistakes

<AccordionGroup>
  <Accordion title="One template per link">
    Templates are for shape, not specific links. Make `Newsletter Weekly`, not `Newsletter Week 19 May 5`.
  </Accordion>

  <Accordion title="Hard-coding utm_content in template">
    `utm_content` differentiates within a template. Leave it blank in the template; fill per-link. Otherwise every link inherits the same content value.
  </Accordion>

  <Accordion title="Templates as the only standard">
    Templates are opt-in - a user can skip them. If consistency matters across the team, pair templates with [UTM Rules](/utm-rules/overview) which enforce standards automatically.
  </Accordion>
</AccordionGroup>

## Edge cases

<Note>
  **Template limit.** Each workspace has a maximum number of templates. Reached the limit? Deactivate or delete unused ones - see [Manage templates](/utm-templates/manage-templates).
</Note>

<Note>
  **Template values still pass through UTM Rules** on link save. A template with `utm_source=Newsletter` becomes `newsletter` if force-lowercase is on.
</Note>