ghost 6.1.0 → 6.3.0

package/core/server/services/member-attribution/AttributionBuilder.js

@@ -7,6 +7,11 @@
  * @prop {string|null} referrerSource
  * @prop {string|null} referrerMedium
  * @prop {string|null} referrerUrl
+ * @prop {string|null} utmSource
+ * @prop {string|null} utmMedium
+ * @prop {string|null} utmCampaign
+ * @prop {string|null} utmTerm
+ * @prop {string|null} utmContent
  */
 
 class Attribution {
@@ -21,9 +26,14 @@ class Attribution {
      * @param {string|null} [data.referrerSource]
      * @param {string|null} [data.referrerMedium]
      * @param {string|null} [data.referrerUrl]
+     * @param {string|null} [data.utmSource]
+     * @param {string|null} [data.utmMedium]
+     * @param {string|null} [data.utmCampaign]
+     * @param {string|null} [data.utmTerm]
+     * @param {string|null} [data.utmContent]
      */
     constructor({
-        id, url, type, referrerSource, referrerMedium, referrerUrl
+        id, url, type, referrerSource, referrerMedium, referrerUrl, utmSource, utmMedium, utmCampaign, utmTerm, utmContent
     }, {urlTranslator}) {
         this.id = id;
         this.url = url;
@@ -31,6 +41,11 @@ class Attribution {
         this.referrerSource = referrerSource;
         this.referrerMedium = referrerMedium;
         this.referrerUrl = referrerUrl;
+        this.utmSource = utmSource;
+        this.utmMedium = utmMedium;
+        this.utmCampaign = utmCampaign;
+        this.utmTerm = utmTerm;
+        this.utmContent = utmContent;
 
         /**
          * @private
@@ -57,7 +72,12 @@ class Attribution {
                     title: null,
                     referrerSource: this.referrerSource,
                     referrerMedium: this.referrerMedium,
-                    referrerUrl: this.referrerUrl
+                    referrerUrl: this.referrerUrl,
+                    utmSource: this.utmSource,
+                    utmMedium: this.utmMedium,
+                    utmCampaign: this.utmCampaign,
+                    utmTerm: this.utmTerm,
+                    utmContent: this.utmContent
                 };
             }
             return {
@@ -67,7 +87,12 @@ class Attribution {
                 title: this.#urlTranslator.getUrlTitle(this.url),
                 referrerSource: this.referrerSource,
                 referrerMedium: this.referrerMedium,
-                referrerUrl: this.referrerUrl
+                referrerUrl: this.referrerUrl,
+                utmSource: this.utmSource,
+                utmMedium: this.utmMedium,
+                utmCampaign: this.utmCampaign,
+                utmTerm: this.utmTerm,
+                utmContent: this.utmContent
             };
         }
 
@@ -80,7 +105,12 @@ class Attribution {
             title: model.get('title') ?? model.get('name') ?? this.#urlTranslator.getUrlTitle(this.url),
             referrerSource: this.referrerSource,
             referrerMedium: this.referrerMedium,
-            referrerUrl: this.referrerUrl
+            referrerUrl: this.referrerUrl,
+            utmSource: this.utmSource,
+            utmMedium: this.utmMedium,
+            utmCampaign: this.utmCampaign,
+            utmTerm: this.utmTerm,
+            utmContent: this.utmContent
         };
     }
 
@@ -118,14 +148,19 @@ class AttributionBuilder {
     /**
      * Creates an Attribution object with the dependencies injected
      */
-    build({id, url, type, referrerSource, referrerMedium, referrerUrl}) {
+    build({id, url, type, referrerSource, referrerMedium, referrerUrl, utmSource, utmMedium, utmCampaign, utmTerm, utmContent}) {
         return new Attribution({
             id,
             url,
             type,
             referrerSource,
             referrerMedium,
-            referrerUrl
+            referrerUrl,
+            utmSource,
+            utmMedium,
+            utmCampaign,
+            utmTerm,
+            utmContent
         }, {urlTranslator: this.urlTranslator});
     }
 
@@ -142,14 +177,24 @@ class AttributionBuilder {
                 type: null,
                 referrerSource: null,
                 referrerMedium: null,
-                referrerUrl: null
+                referrerUrl: null,
+                utmSource: null,
+                utmMedium: null,
+                utmCampaign: null,
+                utmTerm: null,
+                utmContent: null
             });
         }
 
         const referrerData = this.referrerTranslator.getReferrerDetails(history) || {
             referrerSource: null,
             referrerMedium: null,
-            referrerUrl: null
+            referrerUrl: null,
+            utmSource: null,
+            utmMedium: null,
+            utmCampaign: null,
+            utmTerm: null,
+            utmContent: null
         };
 
         // Start at the end. Return the first post we find
@@ -194,10 +239,10 @@ class AttributionBuilder {
 
         // We only have history items without a path that have invalid ids
         return this.build({
-            ...referrerData,
             id: null,
             url: null,
-            type: null
+            type: null,
+            ...referrerData
         });
     }
 }

package/core/server/services/member-attribution/README.md

@@ -0,0 +1,101 @@
+# Member Attribution Service
+
+The Member Attribution Service tracks how members discover and sign up to a Ghost site. It captures attribution data (source pages, referrer information, UTM parameters) and associates it with member signup and subscription events.
+
+## Features
+
+### Core Attribution Tracking
+- **Page Attribution**: Tracks which pages (posts, pages, authors, tags) visitors viewed before becoming members
+- **Referrer Attribution**: Identifies external sources (search engines, social media, direct links) that brought visitors to the site
+- **UTM Parameter Tracking**: Captures UTM campaign parameters (source, medium, campaign, term, content) for marketing attribution
+- **Last Post Algorithm**: Prioritizes the last post viewed in the visitor's journey as the primary attribution source
+
+### Attribution Sources
+- **Content Attribution**: Posts, pages, authors, and tags visited by members
+- **External Referrers**: Tracks referrer sources like Google, Facebook, Twitter, etc. using `@tryghost/referrer-parser`
+- **Manual Creation**: Tracks members created via Admin UI, API, or import tools
+- **Integration Attribution**: Associates members created via integrations with the integration name
+- **Newsletter Links**: Adds attribution tracking to outbound links in newsletters with `?ref=` parameters
+
+### Settings
+- **Member Source Tracking**: Can be enabled/disabled via `members_track_sources` setting
+- **Outbound Link Tagging**: Can be enabled/disabled via `outbound_link_tagging` setting
+
+## Architecture
+
+### Component Overview
+
+```mermaid
+graph TD
+    A[Frontend Browser<br/>member-attribution.js<br/>Captures URL history in session] -->|URLHistory Array| B[MemberAttributionService<br/>Main service interface<br/>Coordinates attribution logic]
+
+    B --> C[AttributionBuilder<br/>Converts URLHistory into Attribution objects<br/>Implements Last Post Algorithm]
+    B --> D[UrlTranslator<br/>Converts paths to resource IDs and types<br/>Fetches Post/Page/Tag/Author models]
+    B --> E[ReferrerTranslator<br/>Parses referrer URLs to identify sources<br/>Extracts UTM parameters]
+    B --> F[OutboundLinkTagger<br/>Adds ?ref parameters to external links]
+
+    C --> D
+    C --> E
+```
+
+### Components
+
+#### 1. **MemberAttributionService** (`MemberAttributionService.js`)
+Main service interface that coordinates all attribution logic.
+
+#### 2. **AttributionBuilder** (`AttributionBuilder.js`)
+Converts URL history into attribution resources using the "Last Post Algorithm™️".
+
+**Key Classes:**
+- `Attribution`: Represents attribution data with methods to fetch and enrich resources
+- `AttributionBuilder`: Factory for creating `Attribution` instances
+
+#### 3. **UrlHistory** (`UrlHistory.js`)
+Validated container for URL history arrays from the frontend.
+
+#### 4. **UrlTranslator** (`UrlTranslator.js`)
+Translates between URLs and Ghost resources.
+
+#### 5. **ReferrerTranslator** (`ReferrerTranslator.js`)
+Parses referrer information into source and medium classifications.
+
+#### 6. **OutboundLinkTagger** (`OutboundLinkTagger.js`)
+Adds `?ref=` parameters to external links in newsletters.
+
+#### 7. **Frontend Script** (`member-attribution.js`)
+Browser-side script that captures visitor journey in sessionStorage.
+
+## Attribution Types
+
+The service supports these attribution types:
+
+| Type     | Description                              | Has ID | Resource Model |
+|----------|------------------------------------------|--------|----------------|
+| `post`   | Blog post                                | ✓      | Post           |
+| `page`   | Static page                              | ✓      | Post           |
+| `author` | Author page                              | ✓      | User           |
+| `tag`    | Tag page                                 | ✓      | Tag            |
+| `url`    | Generic URL (no specific resource)       | ✗      | None           |
+| `null`   | No attribution (tracking disabled/empty) | ✗      | None           |
+
+## Internal Context Sources
+
+When members are created through Ghost's internal systems:
+
+| Context      | referrerSource        | referrerMedium  |
+|--------------|-----------------------|-----------------|
+| `import`     | Imported              | Member Importer |
+| `admin`      | Created manually      | Ghost Admin     |
+| `api`        | Created via API       | Admin API       |
+| `integration`| Integration: {name}   | Admin API       |
+
+## Testing
+
+Tests are located in:
+- `test/unit/server/services/member-attribution/attribution.test.js`
+- `test/unit/server/services/member-attribution/history.test.js`
+- `test/unit/server/services/member-attribution/service.test.js`
+- `test/unit/server/services/member-attribution/url-translator.test.js`
+- `test/unit/server/services/member-attribution/referrer-translator.test.js`
+- `test/unit/server/services/member-attribution/outbound-link-tagger.test.js`
+- `test/e2e-server/services/member-attribution.test.js`

package/core/server/services/member-attribution/ReferrerTranslator.js

@@ -3,6 +3,11 @@
  * @prop {string|null} [referrerSource]
  * @prop {string|null} [referrerMedium]
  * @prop {string|null} [referrerUrl]
+ * @prop {string|null} [utmSource]
+ * @prop {string|null} [utmMedium]
+ * @prop {string|null} [utmCampaign]
+ * @prop {string|null} [utmTerm]
+ * @prop {string|null} [utmContent]
  */
 
 const {ReferrerParser} = require('@tryghost/referrer-parser');
@@ -36,10 +41,40 @@ class ReferrerTranslator {
             return {
                 referrerSource: null,
                 referrerMedium: null,
-                referrerUrl: null
+                referrerUrl: null,
+                utmSource: null,
+                utmMedium: null,
+                utmCampaign: null,
+                utmTerm: null,
+                utmContent: null
             };
         }
 
+        // Look for UTM parameters (earliest entry with UTM data)
+        // Note: history is ordered newest-to-oldest, so we want the LAST match
+        // This captures the original campaign source rather than subsequent navigations
+        let utmData = {
+            utmSource: null,
+            utmMedium: null,
+            utmCampaign: null,
+            utmTerm: null,
+            utmContent: null
+        };
+
+        // In finding the 'campaign' that got the user here, we want the earliest entry with UTM data
+        for (const item of history) {
+            if (item.utmSource || item.utmMedium || item.utmCampaign || item.utmTerm || item.utmContent) {
+                utmData = {
+                    utmSource: item.utmSource || null,
+                    utmMedium: item.utmMedium || null,
+                    utmCampaign: item.utmCampaign || null,
+                    utmTerm: item.utmTerm || null,
+                    utmContent: item.utmContent || null
+                };
+            }
+        }
+
+        // In finding the 'content' that got the user to sign up, we want the latest entry with referrer data
         for (const item of history) {
             let refUrl = this.getUrlFromStr(item.referrerUrl);
             if (refUrl?.hostname === 'checkout.stripe.com') {
@@ -53,7 +88,8 @@ class ReferrerTranslator {
                 return {
                     referrerSource,
                     referrerMedium,
-                    referrerUrl
+                    referrerUrl,
+                    ...utmData
                 };
             }
         }
@@ -61,7 +97,8 @@ class ReferrerTranslator {
         return {
             referrerSource: 'Direct',
             referrerMedium: null,
-            referrerUrl: null
+            referrerUrl: null,
+            ...utmData
         };
     }
 

package/core/server/services/member-attribution/UrlHistory.js

@@ -6,6 +6,11 @@
  * @prop {string} [referrerSource]
  * @prop {string} [referrerMedium]
  * @prop {string} [referrerUrl]
+ * @prop {string} [utmSource]
+ * @prop {string} [utmMedium]
+ * @prop {string} [utmCampaign]
+ * @prop {string} [utmTerm]
+ * @prop {string} [utmContent]
  * @prop {number} time
  */
 

package/core/server/services/members/MembersConfigProvider.js

@@ -1,6 +1,5 @@
 const logging = require('@tryghost/logging');
 const {URL} = require('url');
-const crypto = require('crypto');
 const createKeypair = require('keypair');
 
 class MembersConfigProvider {
@@ -42,20 +41,6 @@ class MembersConfigProvider {
         return this._settingsHelpers.isStripeConnected();
     }
 
-    getAuthSecret() {
-        const hexSecret = this._settingsCache.get('members_email_auth_secret');
-        if (!hexSecret) {
-            logging.warn('Could not find members_email_auth_secret, using dynamically generated secret');
-            return crypto.randomBytes(64);
-        }
-        const secret = Buffer.from(hexSecret, 'hex');
-        if (secret.length < 64) {
-            logging.warn('members_email_auth_secret not large enough (64 bytes), using dynamically generated secret');
-            return crypto.randomBytes(64);
-        }
-        return secret;
-    }
-
     getAllowSelfSignup() {
         // Free signups are allowed only if the site subscription is set to "Full-access"
         // It is blocked for "Invite-only", "Paid-members-only" and "None" accesses

package/core/server/services/members/SingleUseTokenProvider.js

@@ -193,7 +193,7 @@ class SingleUseTokenProvider {
         }
 
         try {
-            const model = await this.model.findOne({id: otcRef});
+            const model = await this.model.findOne({uuid: otcRef});
 
             if (!model) {
                 return false;
@@ -208,16 +208,16 @@ class SingleUseTokenProvider {
     }
 
     /**
-     * @method getIdByToken
-     * Retrieves the ID associated with a given token.
+     * @method getRefByToken
+     * Retrieves the ref associated with a given token.
      *
      * @param {string} token - The token to look up.
-     * @returns {Promise<string|null>} The ID if found, or null if not found or on error.
+     * @returns {Promise<string|null>} The ref if found, or null if not found or on error.
      */
-    async getIdByToken(token) {
+    async getRefByToken(token) {
         try {
             const model = await this.model.findOne({token});
-            return model ? model.get('id') : null;
+            return model ? model.get('uuid') : null;
         } catch (err) {
             return null;
         }
@@ -232,7 +232,7 @@ class SingleUseTokenProvider {
      */
     async getTokenByRef(ref) {
         try {
-            const model = await this.model.findOne({id: ref});
+            const model = await this.model.findOne({uuid: ref});
             return model ? model.get('token') : null;
         } catch (err) {
             return null;
@@ -300,7 +300,7 @@ class SingleUseTokenProvider {
                 return false;
             }
 
-            const tokenId = await this.getIdByToken(token);
+            const tokenId = await this.getRefByToken(token);
             if (!tokenId) {
                 return false;
             }

package/core/server/services/members/api.js

@@ -58,7 +58,7 @@ function createApiInstance(config) {
                 validityPeriod: MAGIC_LINK_TOKEN_VALIDITY,
                 validityPeriodAfterUsage: MAGIC_LINK_TOKEN_VALIDITY_AFTER_USAGE,
                 maxUsageCount: MAGIC_LINK_TOKEN_MAX_USAGE_COUNT,
-                secret: settingsCache.get('members_email_auth_secret')
+                secret: settingsCache.get('members_otc_secret')
             })
         },
         mail: {

package/core/server/services/members/members-api/controllers/RouterController.js

@@ -203,6 +203,11 @@ module.exports = class RouterController {
         delete metadata.referrer_source;
         delete metadata.referrer_medium;
         delete metadata.referrer_url;
+        delete metadata.utm_source;
+        delete metadata.utm_medium;
+        delete metadata.utm_campaign;
+        delete metadata.utm_term;
+        delete metadata.utm_content;
 
         if (metadata.urlHistory) {
             // The full attribution history doesn't fit in the Stripe metadata (can't store objects + limited to 50 keys and 500 chars values)
@@ -236,6 +241,27 @@ module.exports = class RouterController {
             if (attribution.referrerUrl) {
                 metadata.referrer_url = attribution.referrerUrl;
             }
+
+            // UTM parameters
+            if (attribution.utmSource) {
+                metadata.utm_source = attribution.utmSource;
+            }
+
+            if (attribution.utmMedium) {
+                metadata.utm_medium = attribution.utmMedium;
+            }
+
+            if (attribution.utmCampaign) {
+                metadata.utm_campaign = attribution.utmCampaign;
+            }
+
+            if (attribution.utmTerm) {
+                metadata.utm_term = attribution.utmTerm;
+            }
+
+            if (attribution.utmContent) {
+                metadata.utm_content = attribution.utmContent;
+            }
         }
     }
 

package/core/server/services/members/members-api/repositories/MemberRepository.js

@@ -1179,7 +1179,12 @@ module.exports = class MemberRepository {
                 type: data.attribution?.type ?? stripeSubscriptionData.metadata?.attribution_type ?? null,
                 referrerSource: data.attribution?.referrerSource ?? stripeSubscriptionData.metadata?.referrer_source ?? null,
                 referrerMedium: data.attribution?.referrerMedium ?? stripeSubscriptionData.metadata?.referrer_medium ?? null,
-                referrerUrl: data.attribution?.referrerUrl ?? stripeSubscriptionData.metadata?.referrer_url ?? null
+                referrerUrl: data.attribution?.referrerUrl ?? stripeSubscriptionData.metadata?.referrer_url ?? null,
+                utmSource: data.attribution?.utmSource ?? stripeSubscriptionData.metadata?.utm_source ?? null,
+                utmMedium: data.attribution?.utmMedium ?? stripeSubscriptionData.metadata?.utm_medium ?? null,
+                utmCampaign: data.attribution?.utmCampaign ?? stripeSubscriptionData.metadata?.utm_campaign ?? null,
+                utmTerm: data.attribution?.utmTerm ?? stripeSubscriptionData.metadata?.utm_term ?? null,
+                utmContent: data.attribution?.utmContent ?? stripeSubscriptionData.metadata?.utm_content ?? null
             };
 
             const subscriptionCreatedEvent = SubscriptionCreatedEvent.create({

package/core/server/services/members-events/EventStorage.js

@@ -35,6 +35,11 @@ class EventStorage {
                 referrer_source: attribution?.referrerSource ?? null,
                 referrer_medium: attribution?.referrerMedium ?? null,
                 referrer_url: attribution?.referrerUrl ?? null,
+                utm_source: attribution?.utmSource ?? null,
+                utm_medium: attribution?.utmMedium ?? null,
+                utm_campaign: attribution?.utmCampaign ?? null,
+                utm_term: attribution?.utmTerm ?? null,
+                utm_content: attribution?.utmContent ?? null,
                 batch_id: event.data.batchId ?? null
             });
         });
@@ -52,6 +57,11 @@ class EventStorage {
                 referrer_source: attribution?.referrerSource ?? null,
                 referrer_medium: attribution?.referrerMedium ?? null,
                 referrer_url: attribution?.referrerUrl ?? null,
+                utm_source: attribution?.utmSource ?? null,
+                utm_medium: attribution?.utmMedium ?? null,
+                utm_campaign: attribution?.utmCampaign ?? null,
+                utm_term: attribution?.utmTerm ?? null,
+                utm_content: attribution?.utmContent ?? null,
                 batch_id: event.data.batchId ?? null
             });
         });

package/core/server/services/stats/ReferrersStatsService.js

@@ -1,4 +1,5 @@
 const moment = require('moment');
+const errors = require('@tryghost/errors');
 
 // Import centralized date utilities
 const {getDateBoundaries, applyDateFilter} = require('./utils/date-utils');
@@ -455,6 +456,138 @@ class ReferrersStatsService {
             meta: {}
         };
     }
+
+    /**
+     * Get UTM growth stats broken down by UTM parameter (fixture data for now)
+     * @param {Object} options
+     * @param {string} [options.utm_type='utm_source'] - Which UTM field to group by ('utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content')
+     * @param {string} [options.order='free_members desc'] - Sort order
+     * @param {number} [options.limit=50] - Maximum number of results
+     * @param {string} [options.post_id] - Optional filter by post ID
+     * @returns {Promise<{data: UtmGrowthStat[], meta: {}}>}
+     */
+    async getUtmGrowthStats(options = {}) {
+        const utmField = options.utm_type || 'utm_source';
+        const limit = options.limit || 50;
+        const postId = options.post_id;
+
+        // Validate utm_type is a valid UTM field
+        const validUtmFields = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+        if (!validUtmFields.includes(utmField)) {
+            throw new errors.BadRequestError({
+                message: `Invalid utm_type: ${utmField}. Must be one of: ${validUtmFields.join(', ')}`
+            });
+        }
+
+        // Fixture data; will replace with real data once members service is wired up fully
+        let fixtureData = this._getUtmFixtureData(utmField);
+
+        // If filtering by post, scale down the data
+        if (postId) {
+            fixtureData = fixtureData.map(item => ({
+                ...item,
+                free_members: Math.floor(item.free_members * 0.3), // 30% of global
+                paid_members: Math.floor(item.paid_members * 0.25), // 25% of global
+                mrr: Math.floor(item.mrr * 0.25) // 25% of global
+            })).filter(item => item.free_members > 0 || item.paid_members > 0); // Only include items with data
+        }
+
+        const sortedData = this._sortUtmData(fixtureData, options.order);
+        const limitedData = postId ? sortedData : (limit > 0 ? sortedData.slice(0, limit) : sortedData);
+
+        return {
+            data: limitedData,
+            meta: {}
+        };
+    }
+
+    /**
+     * Generate fixture data for UTM parameters
+     * @private
+     * @param {string} utmField - The UTM field ('utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content')
+     * @returns {UtmGrowthStat[]}
+     */
+    _getUtmFixtureData(utmField) {
+        const fixtures = {
+            utm_source: [
+                {utm_value: 'google', utm_type: 'utm_source', free_members: 100, paid_members: 20, mrr: 10000},
+                {utm_value: 'facebook', utm_type: 'utm_source', free_members: 80, paid_members: 15, mrr: 7500},
+                {utm_value: 'twitter', utm_type: 'utm_source', free_members: 60, paid_members: 10, mrr: 5000},
+                {utm_value: 'newsletter', utm_type: 'utm_source', free_members: 40, paid_members: 25, mrr: 12500},
+                {utm_value: 'linkedin', utm_type: 'utm_source', free_members: 35, paid_members: 12, mrr: 6000},
+                {utm_value: 'reddit', utm_type: 'utm_source', free_members: 25, paid_members: 5, mrr: 2500},
+                {utm_value: 'youtube', utm_type: 'utm_source', free_members: 20, paid_members: 8, mrr: 4000},
+                {utm_value: 'instagram', utm_type: 'utm_source', free_members: 18, paid_members: 6, mrr: 3000}
+            ],
+            utm_medium: [
+                {utm_value: 'organic', utm_type: 'utm_medium', free_members: 150, paid_members: 30, mrr: 15000},
+                {utm_value: 'cpc', utm_type: 'utm_medium', free_members: 90, paid_members: 20, mrr: 10000},
+                {utm_value: 'email', utm_type: 'utm_medium', free_members: 70, paid_members: 20, mrr: 10000},
+                {utm_value: 'social', utm_type: 'utm_medium', free_members: 30, paid_members: 10, mrr: 5000},
+                {utm_value: 'referral', utm_type: 'utm_medium', free_members: 25, paid_members: 8, mrr: 4000},
+                {utm_value: 'display', utm_type: 'utm_medium', free_members: 15, paid_members: 3, mrr: 1500}
+            ],
+            utm_campaign: [
+                {utm_value: 'spring-sale', utm_type: 'utm_campaign', free_members: 120, paid_members: 35, mrr: 17500},
+                {utm_value: 'product-launch', utm_type: 'utm_campaign', free_members: 80, paid_members: 20, mrr: 10000},
+                {utm_value: 'webinar-series', utm_type: 'utm_campaign', free_members: 60, paid_members: 15, mrr: 7500},
+                {utm_value: 'holiday-promo', utm_type: 'utm_campaign', free_members: 45, paid_members: 18, mrr: 9000},
+                {utm_value: 'content-upgrade', utm_type: 'utm_campaign', free_members: 30, paid_members: 8, mrr: 4000},
+                {utm_value: 'partner-collab', utm_type: 'utm_campaign', free_members: 25, paid_members: 12, mrr: 6000}
+            ],
+            utm_term: [
+                {utm_value: 'best-email-marketing', utm_type: 'utm_term', free_members: 85, paid_members: 22, mrr: 11000},
+                {utm_value: 'ghost-cms', utm_type: 'utm_term', free_members: 70, paid_members: 18, mrr: 9000},
+                {utm_value: 'newsletter-platform', utm_type: 'utm_term', free_members: 55, paid_members: 15, mrr: 7500},
+                {utm_value: 'content-management', utm_type: 'utm_term', free_members: 40, paid_members: 10, mrr: 5000},
+                {utm_value: 'publishing-platform', utm_type: 'utm_term', free_members: 30, paid_members: 8, mrr: 4000},
+                {utm_value: 'membership-software', utm_type: 'utm_term', free_members: 20, paid_members: 5, mrr: 2500}
+            ],
+            utm_content: [
+                {utm_value: 'hero-cta', utm_type: 'utm_content', free_members: 95, paid_members: 25, mrr: 12500},
+                {utm_value: 'sidebar-banner', utm_type: 'utm_content', free_members: 75, paid_members: 18, mrr: 9000},
+                {utm_value: 'footer-link', utm_type: 'utm_content', free_members: 50, paid_members: 12, mrr: 6000},
+                {utm_value: 'email-button', utm_type: 'utm_content', free_members: 45, paid_members: 15, mrr: 7500},
+                {utm_value: 'popup-form', utm_type: 'utm_content', free_members: 35, paid_members: 8, mrr: 4000},
+                {utm_value: 'text-link', utm_type: 'utm_content', free_members: 25, paid_members: 6, mrr: 3000}
+            ]
+        };
+
+        return fixtures[utmField] || fixtures.utm_source;
+    }
+
+    /**
+     * Sort UTM data by the specified order
+     * @private
+     * @param {UtmGrowthStat[]} data
+     * @param {string} [order='free_members desc']
+     * @returns {UtmGrowthStat[]}
+     */
+    _sortUtmData(data, order = 'free_members desc') {
+        const [field, direction] = order.split(' ');
+        const validFields = ['free_members', 'paid_members', 'mrr', 'utm_value'];
+
+        if (!validFields.includes(field)) {
+            return data;
+        }
+
+        return [...data].sort((a, b) => {
+            let valueA = a[field];
+            let valueB = b[field];
+
+            // Handle string sorting for utm_value
+            if (field === 'utm_value') {
+                valueA = String(valueA).toLowerCase();
+                valueB = String(valueB).toLowerCase();
+            }
+
+            if (direction === 'asc') {
+                return valueA < valueB ? -1 : valueA > valueB ? 1 : 0;
+            }
+            // Default to desc
+            return valueA < valueB ? 1 : valueA > valueB ? -1 : 0;
+        });
+    }
 }
 
 module.exports = ReferrersStatsService;
@@ -507,3 +640,13 @@ module.exports.normalizeSource = normalizeSource;
  * @property {number} mrr Total MRR from this source (in cents)
  * @property {string} date The date (YYYY-MM-DD) on which these counts were recorded
  **/
+
+/**
+ * @typedef {object} UtmGrowthStat
+ * @type {Object}
+ * @property {string} utm_value - The UTM parameter value (e.g., 'google', 'facebook')
+ * @property {string} utm_type - The UTM parameter type ('utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content')
+ * @property {number} free_members - Count of free member signups
+ * @property {number} paid_members - Count of paid member conversions
+ * @property {number} mrr - Total MRR from this UTM parameter (in cents)
+ **/