feat: attribute payment intent through paywall, checkout, and top-up telemetry

src/components/topbar/CurrentUserPopoverLegacy.vue

@@ -224,7 +224,7 @@ const handleOpenUserSettings = () => {
 }
 
 const handleOpenPlansAndPricing = () => {
-  subscriptionDialog.showPricingTable()
+  subscriptionDialog.showPricingTable({ reason: 'avatar_menu_plans' })
   emit('close')
 }
 
@@ -239,8 +239,7 @@ const handleOpenPlanAndCreditsSettings = () => {
 }
 
 const handleTopUp = () => {
-  // Track purchase credits entry from avatar popover
-  useTelemetry()?.trackAddApiCreditButtonClicked()
+  useTelemetry()?.trackAddApiCreditButtonClicked({ source: 'avatar_menu' })
   dialogService.showTopUpCreditsDialog()
   emit('close')
 }
@@ -254,7 +253,7 @@ const handleOpenPartnerNodesInfo = () => {
 }
 
 const handleUpgradeToAddCredits = () => {
-  subscriptionDialog.showPricingTable()
+  subscriptionDialog.showPricingTable({ reason: 'upgrade_to_add_credits' })
   emit('close')
 }
 

src/components/topbar/TopbarSubscribeButton.vue

@@ -21,6 +21,6 @@ const { isFreeTier } = useBillingContext()
 const subscriptionDialog = useSubscriptionDialog()
 
 function handleClick() {
-  subscriptionDialog.showPricingTable()
+  subscriptionDialog.showPricingTable({ reason: 'subscribe_now_button' })
 }
 </script>

src/composables/billing/types.ts

@@ -1,5 +1,6 @@
 import type { ComputedRef, Ref } from 'vue'
 
+import type { SubscriptionDialogOptions } from '@/platform/cloud/subscription/composables/useSubscriptionDialog'
 import type { TierKey } from '@/platform/cloud/subscription/constants/tierPricing'
 import type {
   BillingStatus,
@@ -75,9 +76,10 @@ export interface BillingActions {
    */
   requireActiveSubscription: () => Promise<void>
   /**
-   * Shows the subscription dialog.
+   * Shows the subscription dialog. Pass a reason so the paywall open and any
+   * downstream checkout stay attributed to the triggering product moment.
    */
-  showSubscriptionDialog: () => void
+  showSubscriptionDialog: (options?: SubscriptionDialogOptions) => void
 }
 
 export interface BillingState {

src/composables/billing/useBillingContext.ts

@@ -7,6 +7,7 @@ import {
   getTierFeatures
 } from '@/platform/cloud/subscription/constants/tierPricing'
 import type { TierKey } from '@/platform/cloud/subscription/constants/tierPricing'
+import type { SubscriptionDialogOptions } from '@/platform/cloud/subscription/composables/useSubscriptionDialog'
 import type {
   PreviewSubscribeOptions,
   SubscribeOptions
@@ -281,8 +282,8 @@ function useBillingContextInternal(): BillingContext {
     return activeContext.value.requireActiveSubscription()
   }
 
-  function showSubscriptionDialog() {
-    return activeContext.value.showSubscriptionDialog()
+  function showSubscriptionDialog(options?: SubscriptionDialogOptions) {
+    return activeContext.value.showSubscriptionDialog(options)
   }
 
   return {

src/composables/billing/useLegacyBilling.ts

@@ -2,6 +2,7 @@ import { computed, ref } from 'vue'
 
 import { useAuthActions } from '@/composables/auth/useAuthActions'
 import { useSubscription } from '@/platform/cloud/subscription/composables/useSubscription'
+import type { SubscriptionDialogOptions } from '@/platform/cloud/subscription/composables/useSubscriptionDialog'
 import type {
   BillingStatus,
   BillingSubscriptionStatus,
@@ -189,12 +190,12 @@ export function useLegacyBilling(): BillingState & BillingActions {
   async function requireActiveSubscription(): Promise<void> {
     await fetchStatus()
     if (!isActiveSubscription.value) {
-      legacyShowSubscriptionDialog()
+      legacyShowSubscriptionDialog({ reason: 'subscription_required' })
     }
   }
 
-  function showSubscriptionDialog(): void {
-    legacyShowSubscriptionDialog()
+  function showSubscriptionDialog(options?: SubscriptionDialogOptions): void {
+    legacyShowSubscriptionDialog(options)
   }
 
   return {

src/composables/useCoreCommands.ts

@@ -503,7 +503,7 @@ export function useCoreCommands(): ComfyCommand[] {
       }) => {
         trackRunButton(metadata)
         if (!isActiveSubscription.value) {
-          showSubscriptionDialog()
+          showSubscriptionDialog({ reason: 'subscribe_to_run' })
           return
         }
 
@@ -526,7 +526,7 @@ export function useCoreCommands(): ComfyCommand[] {
       }) => {
         trackRunButton(metadata)
         if (!isActiveSubscription.value) {
-          showSubscriptionDialog()
+          showSubscriptionDialog({ reason: 'subscribe_to_run' })
           return
         }
 
@@ -548,7 +548,7 @@ export function useCoreCommands(): ComfyCommand[] {
       }) => {
         trackRunButton(metadata)
         if (!isActiveSubscription.value) {
-          showSubscriptionDialog()
+          showSubscriptionDialog({ reason: 'subscribe_to_run' })
           return
         }
 

src/platform/assets/components/UploadModelUpgradeModal.vue

@@ -25,6 +25,6 @@ function handleClose() {
 }
 
 function handleSubscribe() {
-  showSubscriptionDialog()
+  showSubscriptionDialog({ reason: 'upload_model_upgrade' })
 }
 </script>

src/platform/cloud/onboarding/CloudSubscriptionRedirectView.test.ts

@@ -140,7 +140,8 @@ describe('CloudSubscriptionRedirectView', () => {
     expect(mockPerformSubscriptionCheckout).toHaveBeenCalledWith(
       'creator',
       'monthly',
-      false
+      false,
+      'deep_link'
     )
 
     // Shows loading affordances
@@ -169,7 +170,8 @@ describe('CloudSubscriptionRedirectView', () => {
     expect(mockPerformSubscriptionCheckout).toHaveBeenCalledWith(
       'creator',
       'monthly',
-      false
+      false,
+      'deep_link'
     )
   })
 

src/platform/cloud/onboarding/CloudSubscriptionRedirectView.vue

@@ -112,7 +112,12 @@ const runRedirect = wrapWithErrorHandlingAsync(async () => {
   if (isActiveSubscription.value) {
     await accessBillingPortal(undefined, false)
   } else {
-    await performSubscriptionCheckout(tierKeyParam, billingCycle, false)
+    await performSubscriptionCheckout(
+      tierKeyParam,
+      billingCycle,
+      false,
+      'deep_link'
+    )
   }
 }, reportError)
 

src/platform/cloud/subscription/components/CreditsTile.vue

@@ -351,12 +351,12 @@ const handleRefresh = wrapWithErrorHandlingAsync(async () => {
 })
 
 function handleAddCredits() {
-  telemetry?.trackAddApiCreditButtonClicked()
+  telemetry?.trackAddApiCreditButtonClicked({ source: 'credits_panel' })
   void dialogService.showTopUpCreditsDialog()
 }
 
 function handleUpgradeToAddCredits() {
-  showPricingTable()
+  showPricingTable({ reason: 'upgrade_to_add_credits' })
 }
 
 async function handleWindowFocus() {

src/platform/cloud/subscription/components/FreeTierDialogContent.test.ts

@@ -5,6 +5,8 @@ import { render, screen } from '@testing-library/vue'
 
 import enMessages from '@/locales/en/main.json' with { type: 'json' }
 
+import type { SubscriptionDialogReason } from '@/platform/cloud/subscription/composables/useSubscriptionDialog'
+
 import FreeTierDialogContent from './FreeTierDialogContent.vue'
 
 const mockRenewalDate = vi.hoisted(() => ({ value: null as string | null }))
@@ -15,14 +17,15 @@ vi.mock('@/composables/billing/useBillingContext', () => ({
   }))
 }))
 
-function renderComponent() {
+function renderComponent(props?: { reason?: SubscriptionDialogReason }) {
   const i18n = createI18n({
     legacy: false,
     locale: 'en',
     messages: { en: enMessages }
   })
 
   return render(FreeTierDialogContent, {
+    props,
     global: {
       plugins: [i18n]
     }
@@ -43,4 +46,18 @@ describe('FreeTierDialogContent', () => {
     renderComponent()
     expect(screen.queryByText(/credits refresh on/)).not.toBeInTheDocument()
   })
+
+  it('keeps the generic copy for intent reasons outside the credits variants', () => {
+    mockRenewalDate.value = '2026-07-15T10:00:00Z'
+    renderComponent({ reason: 'subscribe_to_run' })
+    expect(
+      screen.getByText('Your credits refresh on Jul 15, 2026.')
+    ).toBeInTheDocument()
+  })
+
+  it('swaps to the out-of-credits copy without the refresh line', () => {
+    mockRenewalDate.value = '2026-07-15T10:00:00Z'
+    renderComponent({ reason: 'out_of_credits' })
+    expect(screen.queryByText(/credits refresh on/)).not.toBeInTheDocument()
+  })
 })

src/platform/cloud/subscription/components/FreeTierDialogContent.vue

@@ -52,7 +52,7 @@
           </p>
 
           <p
-            v-if="!reason || reason === 'subscription_required'"
+            v-if="!isCreditsBlockedVariant"
             class="m-0 text-sm text-text-secondary"
           >
             {{
@@ -65,10 +65,7 @@
           </p>
 
           <p
-            v-if="
-              (!reason || reason === 'subscription_required') &&
-              formattedRenewalDate
-            "
+            v-if="!isCreditsBlockedVariant && formattedRenewalDate"
             class="m-0 text-sm text-text-secondary"
           >
             {{
@@ -88,7 +85,7 @@
           @click="$emit('upgrade')"
         >
           {{
-            reason === 'out_of_credits' || reason === 'top_up_blocked'
+            isCreditsBlockedVariant
               ? $t('subscription.freeTier.upgradeCta')
               : $t('subscription.freeTier.subscribeCta')
           }}
@@ -107,7 +104,7 @@ import type { SubscriptionDialogReason } from '@/platform/cloud/subscription/com
 import SubscriptionBenefits from '@/platform/cloud/subscription/components/SubscriptionBenefits.vue'
 import { getTierCredits } from '@/platform/cloud/subscription/constants/tierPricing'
 
-defineProps<{
+const { reason } = defineProps<{
   reason?: SubscriptionDialogReason
 }>()
 
@@ -129,4 +126,10 @@ const formattedRenewalDate = computed(() => {
 })
 
 const freeTierCredits = computed(() => getTierCredits('free'))
+
+// Only these two variants replace the generic free-tier copy; any other
+// intent reason (subscribe_to_run, deep_link, ...) keeps the default pitch.
+const isCreditsBlockedVariant = computed(
+  () => reason === 'out_of_credits' || reason === 'top_up_blocked'
+)
 </script>

src/platform/cloud/subscription/components/PricingTable.test.ts

@@ -261,6 +261,7 @@ describe('PricingTable', () => {
         tier: 'creator',
         cycle: 'yearly',
         checkout_type: 'change',
+        checkout_attempt_id: expect.any(String),
         previous_tier: 'standard'
       })
       expect(mockAccessBillingPortal).toHaveBeenCalledWith('creator-yearly')
@@ -341,6 +342,7 @@ describe('PricingTable', () => {
       expect(
         window.localStorage.getItem(PENDING_SUBSCRIPTION_CHECKOUT_STORAGE_KEY)
       ).toBeNull()
+      expect(mockTrackBeginCheckout).not.toHaveBeenCalled()
     })
 
     it('should use the latest userId value when it changes after mount', async () => {
@@ -366,6 +368,7 @@ describe('PricingTable', () => {
         tier: 'creator',
         cycle: 'yearly',
         checkout_type: 'change',
+        checkout_attempt_id: expect.any(String),
         previous_tier: 'standard'
       })
     })

src/platform/cloud/subscription/components/PricingTable.vue

@@ -277,6 +277,7 @@ import type {
   TierKey,
   TierPricing
 } from '@/platform/cloud/subscription/constants/tierPricing'
+import type { SubscriptionDialogReason } from '@/platform/cloud/subscription/composables/useSubscriptionDialog'
 import { recordPendingSubscriptionCheckoutAttempt } from '@/platform/cloud/subscription/utils/subscriptionCheckoutTracker'
 import { performSubscriptionCheckout } from '@/platform/cloud/subscription/utils/subscriptionCheckoutUtil'
 import { isPlanDowngrade } from '@/platform/cloud/subscription/utils/subscriptionTierRank'
@@ -321,6 +322,10 @@ interface PricingTierConfig {
   isPopular?: boolean
 }
 
+const { reason } = defineProps<{
+  reason?: SubscriptionDialogReason
+}>()
+
 const emit = defineEmits<{
   chooseTeamWorkspace: []
 }>()
@@ -463,16 +468,17 @@ const handleSubscribe = wrapWithErrorHandlingAsync(
         } as const
         const previousPlan = currentPlanDescriptor.value
         const checkoutAttribution = await getCheckoutAttributionForCloud()
-        if (userId.value) {
-          telemetry?.trackBeginCheckout({
-            user_id: userId.value,
-            tier: targetPlan.tierKey,
-            cycle: targetPlan.billingCycle,
-            checkout_type: 'change',
-            ...checkoutAttribution,
-            ...(previousPlan ? { previous_tier: previousPlan.tierKey } : {})
-          })
-        }
+        const beginCheckoutMetadata = userId.value
+          ? {
+              user_id: userId.value,
+              tier: targetPlan.tierKey,
+              cycle: targetPlan.billingCycle,
+              checkout_type: 'change' as const,
+              ...(reason ? { payment_intent_source: reason } : {}),
+              ...checkoutAttribution,
+              ...(previousPlan ? { previous_tier: previousPlan.tierKey } : {})
+            }
+          : null
         // Pass the target tier to create a deep link to subscription update confirmation
         const checkoutTier = getCheckoutTier(
           targetPlan.tierKey,
@@ -487,28 +493,39 @@ const handleSubscribe = wrapWithErrorHandlingAsync(
 
         if (downgrade) {
           // TODO(COMFY-StripeProration): Remove once backend checkout creation mirrors portal proration ("change at billing end")
-          await accessBillingPortal()
+          const didOpenPortal = await accessBillingPortal()
+          if (didOpenPortal && beginCheckoutMetadata) {
+            telemetry?.trackBeginCheckout(beginCheckoutMetadata)
+          }
         } else {
           const didOpenPortal = await accessBillingPortal(checkoutTier)
           if (!didOpenPortal) {
             return
           }
 
-          recordPendingSubscriptionCheckoutAttempt({
+          const pendingAttempt = recordPendingSubscriptionCheckoutAttempt({
             tier: targetPlan.tierKey,
             cycle: targetPlan.billingCycle,
             checkout_type: 'change',
+            payment_intent_source: reason,
             ...(previousPlan ? { previous_tier: previousPlan.tierKey } : {}),
             ...(previousPlan
               ? { previous_cycle: previousPlan.billingCycle }
               : {})
           })
+          if (beginCheckoutMetadata) {
+            telemetry?.trackBeginCheckout({
+              ...beginCheckoutMetadata,
+              checkout_attempt_id: pendingAttempt.attempt_id
+            })
+          }
         }
       } else {
         await performSubscriptionCheckout(
           tierKey,
           currentBillingCycle.value,
-          true
+          true,
+          reason
         )
       }
     } finally {