Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(studio): add upgrade CTA placement experiment (#45858)

Mert YEREKAPAN2191669d0867
diff --git a/apps/studio/components/interfaces/Home/ProjectList/EmptyStates.tsx b/apps/studio/components/interfaces/Home/ProjectList/EmptyStates.tsx
index 77f982a5612..4c4aa6a94a0 100644
--- a/apps/studio/components/interfaces/Home/ProjectList/EmptyStates.tsx
+++ b/apps/studio/components/interfaces/Home/ProjectList/EmptyStates.tsx
@@ -1,6 +1,7 @@
import { BoxPlus } from 'icons'
import { Plus } from 'lucide-react'
import Link from 'next/link'
+import { ReactNode } from 'react'
import {
Button,
Card,
@@ -65,9 +66,10 @@ export const LoadingTableView = () => {
)
}
-export const LoadingCardView = () => {
+export const LoadingCardView = ({ prependCard }: { prependCard?: ReactNode }) => {
return (
<ul className="w-full mx-auto grid grid-cols-1 gap-4 sm:grid-cols-1 md:grid-cols-1 lg:grid-cols-2 xl:grid-cols-3">
+ {prependCard}
<ShimmeringCard />
<ShimmeringCard />
</ul>
diff --git a/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx b/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
index ed387e578bc..be8d7986a29 100644
--- a/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
+++ b/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
@@ -2,7 +2,7 @@ import { keepPreviousData } from '@tanstack/react-query'
import { useDebounce } from '@uidotdev/usehooks'
import { LOCAL_STORAGE_KEYS, useParams } from 'common'
import { parseAsArrayOf, parseAsString, parseAsStringLiteral, useQueryState } from 'nuqs'
-import { useMemo } from 'react'
+import { ReactNode, useMemo } from 'react'
import {
Card,
cn,
@@ -40,9 +40,19 @@ import type { Organization } from '@/types'
export interface ProjectListProps {
organization?: Organization
rewriteHref?: (projectRef: string) => string
+ /**
+ * Optional content rendered as the first `<li>` inside the grid view, before the
+ * project cards. Used by the upgrade CTA placement experiment to slot a card-shaped
+ * usage tile in the project list. Ignored in table view.
+ */
+ prependCard?: ReactNode
}
-export const ProjectList = ({ organization: organization_, rewriteHref }: ProjectListProps) => {
+export const ProjectList = ({
+ organization: organization_,
+ rewriteHref,
+ prependCard,
+}: ProjectListProps) => {
const { slug: urlSlug } = useParams()
const { data: selectedOrganization } = useSelectedOrganizationQuery()
@@ -150,7 +160,11 @@ export const ProjectList = ({ organization: organization_, rewriteHref }: Projec
}
if (isLoadingPermissions || isLoadingProjects || !organization) {
- return viewMode === 'table' ? <LoadingTableView /> : <LoadingCardView />
+ return viewMode === 'table' ? (
+ <LoadingTableView />
+ ) : (
+ <LoadingCardView prependCard={prependCard} />
+ )
}
if (isEmpty) {
@@ -159,7 +173,7 @@ export const ProjectList = ({ organization: organization_, rewriteHref }: Projec
if (viewMode === 'table') {
return (
- <Card className="flex-1 min-h-0 overflow-y-auto mb-8">
+ <Card className="flex-1 min-h-0 overflow-y-auto">
<Table>
{/* [Joshen] Ideally we can figure out sticky table headers here */}
<TableHeader>
@@ -277,7 +291,7 @@ export const ProjectList = ({ organization: organization_, rewriteHref }: Projec
) : noResultsFromSearch ? (
<NoSearchResults searchString={search} />
) : (
- <div className="flex flex-col gap-y-2 md:gap-y-4 pb-6">
+ <div className="flex flex-col gap-y-2 md:gap-y-4">
<ul
className={cn(
'min-h-0 w-full mx-auto',
@@ -285,6 +299,7 @@ export const ProjectList = ({ organization: organization_, rewriteHref }: Projec
'sm:grid-cols-1 md:grid-cols-1 lg:grid-cols-2 xl:grid-cols-3'
)}
>
+ {prependCard}
{orgProjects?.map((project) => (
<ProjectCard
key={project.ref}
diff --git a/apps/studio/components/interfaces/ProjectHome/PlanUsageCard.tsx b/apps/studio/components/interfaces/ProjectHome/PlanUsageCard.tsx
new file mode 100644
index 00000000000..7c5883468f8
--- /dev/null
+++ b/apps/studio/components/interfaces/ProjectHome/PlanUsageCard.tsx
@@ -0,0 +1,252 @@
+import { ChevronRight } from 'lucide-react'
+import Link from 'next/link'
+import { cn } from 'ui'
+
+import { UpgradePlanButton } from '@/components/ui/UpgradePlanButton'
+import { PricingMetric } from '@/data/analytics/org-daily-stats-query'
+import { OrgMetricsUsage, useOrgUsageQuery } from '@/data/usage/org-usage-query'
+import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+import { useTrack } from '@/lib/telemetry/track'
+
+type MetricUnit = 'gigabytes' | 'count'
+
+type MetricConfig = {
+ key: PricingMetric
+ label: string
+ unit: MetricUnit
+ /** Anchor id of the matching section on the org usage page. */
+ anchor: string
+}
+
+const METRICS: MetricConfig[] = [
+ { key: PricingMetric.EGRESS, label: 'Egress', unit: 'gigabytes', anchor: 'egress' },
+ {
+ key: PricingMetric.DATABASE_SIZE,
+ label: 'Database size',
+ unit: 'gigabytes',
+ anchor: 'databaseSize',
+ },
+ {
+ key: PricingMetric.MONTHLY_ACTIVE_USERS,
+ label: 'Monthly active users',
+ unit: 'count',
+ anchor: 'mau',
+ },
+ {
+ key: PricingMetric.STORAGE_SIZE,
+ label: 'File storage',
+ unit: 'gigabytes',
+ anchor: 'storageSize',
+ },
+]
+
+const formatGigabytes = (value: number) => {
+ if (value === 0) return '0 GB'
+ if (value < 1) return `${(value * 1000).toFixed(0)} MB`
+ return `${value.toFixed(value < 10 ? 2 : 1)} GB`
+}
+
+const formatGigabyteLimit = (limit: number) => {
+ if (limit < 1) return `${(limit * 1000).toFixed(0)} MB`
+ return `${limit} GB`
+}
+
+const formatCount = (value: number) => {
+ if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`
+ if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k`
+ return value.toLocaleString()
+}
+
+const formatCountLimit = (limit: number) => {
+ if (limit >= 1_000_000) return `${(limit / 1_000_000).toFixed(0)}M`
+ if (limit >= 1_000) return `${(limit / 1_000).toFixed(0)}k`
+ return limit.toLocaleString()
+}
+
+const formatValue = (value: number, unit: MetricUnit) =>
+ unit === 'gigabytes' ? formatGigabytes(value) : formatCount(value)
+
+const formatLimit = (limit: number, unit: MetricUnit) =>
+ unit === 'gigabytes' ? formatGigabyteLimit(limit) : formatCountLimit(limit)
+
+const RING_RADIUS = 7
+const RING_CIRCUMFERENCE = 2 * Math.PI * RING_RADIUS
+
+const ProgressRing = ({
+ ratio,
+ isOver,
+ isApproaching,
+}: {
+ ratio: number
+ isOver: boolean
+ isApproaching: boolean
+}) => {
+ const clamped = Math.max(0, Math.min(1, ratio))
+ const offset = RING_CIRCUMFERENCE * (1 - clamped)
+ return (
+ <svg
+ width="16"
+ height="16"
+ viewBox="0 0 18 18"
+ className="shrink-0"
+ aria-hidden="true"
+ role="presentation"
+ >
+ <circle
+ cx="9"
+ cy="9"
+ r={RING_RADIUS}
+ strokeWidth="2"
+ fill="none"
+ stroke="currentColor"
+ className="text-foreground-muted/40"
+ />
+ <circle
+ cx="9"
+ cy="9"
+ r={RING_RADIUS}
+ strokeWidth="2"
+ fill="none"
+ stroke="currentColor"
+ strokeDasharray={RING_CIRCUMFERENCE}
+ strokeDashoffset={offset}
+ strokeLinecap="round"
+ transform="rotate(-90 9 9)"
+ className={cn(
+ 'transition-[stroke-dashoffset] duration-500',
+ isOver ? 'text-warning-600' : isApproaching ? 'text-warning' : 'text-brand'
+ )}
+ />
+ </svg>
+ )
+}
+
+// The upgrade CTA placement experiment variant this card represents. Used as the telemetry
+// `source` + `placement` value. Kept as a constant so the tracking stays explicit.
+const PLACEMENT = 'org_projects_list'
+
+const CompactMetricRow = ({
+ usageItem,
+ config,
+ orgSlug,
+}: {
+ usageItem: OrgMetricsUsage
+ config: MetricConfig
+ orgSlug: string
+}) => {
+ const current = usageItem.usage ?? 0
+ const limit = usageItem.pricing_free_units ?? 0
+ const ratio = limit > 0 ? current / limit : 0
+ const isOver = limit > 0 && current >= limit
+ const isApproaching = limit > 0 && ratio >= 0.8 && !isOver
+
+ return (
+ <Link
+ href={`/org/${orgSlug}/usage#${config.anchor}`}
+ className="group/row block px-4 hover:bg-surface-200 transition-colors"
+ >
+ <div className="flex items-center justify-between gap-2 py-2 border-t border-dashed">
+ <div className="flex items-center gap-2 min-w-0">
+ <ProgressRing ratio={ratio} isOver={isOver} isApproaching={isApproaching} />
+ <span className="text-[11px] text-foreground-light uppercase font-mono truncate">
+ {config.label}
+ </span>
+ </div>
+ <div className="flex items-center shrink-0">
+ <span className="text-[11px] font-mono tabular-nums whitespace-nowrap">
+ <span className={cn(isOver ? 'text-warning' : 'text-foreground')}>
+ {formatValue(current, config.unit)}
+ </span>
+ <span className="text-muted"> / </span>
+ <span className="text-foreground-lighter"> {formatLimit(limit, config.unit)}</span>
+ </span>
+ <ChevronRight
+ size={12}
+ strokeWidth={1.5}
+ className="text-foreground w-0 ml-0 opacity-0 overflow-hidden group-hover/row:w-3 group-hover/row:ml-1 group-hover/row:opacity-100 transition-all"
+ />
+ </div>
+ </div>
+ </Link>
+ )
+}
+
+const SkeletonMetricRow = ({ label }: { label: string }) => (
+ <div className="px-4">
+ <div className="flex items-center justify-between gap-2 py-2 border-t border-dashed">
+ <div className="flex items-center gap-2 min-w-0">
+ <div
+ className="w-4 h-4 rounded-full border-2 border-foreground-muted/40 shrink-0"
+ aria-hidden
+ />
+ <span className="text-xs text-foreground-light truncate">{label}</span>
+ </div>
+ <div className="h-3 w-16 rounded bg-surface-200 animate-pulse" aria-hidden />
+ </div>
+ </div>
+)
+
+/**
+ * Renders the upgrade CTA's plan-usage card as the first tile in the org project list
+ * (the `org_projects_list` experiment variant). The parent is responsible for gating on
+ * the experiment variant + free plan — this component only renders the visual sections
+ * once usage data is available. Shaped like a `ProjectCard` so it reads as another tile.
+ */
+export const PlanUsageCard = () => {
+ const track = useTrack()
+ const { data: organization } = useSelectedOrganizationQuery()
+ const { data: usage, isSuccess, isError } = useOrgUsageQuery({ orgSlug: organization?.slug })
+
+ const visibleRows = isSuccess
+ ? METRICS.map((config) => {
+ const usageItem = usage.usages.find((u) => u.metric === config.key)
+ if (!usageItem) return null
+ if (!usageItem.available_in_plan) return null
+ if (!usageItem.pricing_free_units || usageItem.pricing_free_units <= 0) return null
+ return { config, usageItem }
+ }).filter((row): row is { config: MetricConfig; usageItem: OrgMetricsUsage } => row !== null)
+ : []
+
+ // Hide entirely on hard error or when the org has zero applicable metrics — both
+ // are extreme edge cases. Otherwise always render the card shell so the layout is
+ // reserved from first paint and the usage rows fade in once the query resolves.
+ if (isError) return null
+ if (isSuccess && visibleRows.length === 0) return null
+
+ return (
+ <li className="list-none h-min">
+ <div
+ className={cn(
+ 'group relative bg-surface-100 border border-surface rounded-md',
+ 'flex flex-col gap-y-2'
+ )}
+ >
+ <div className="flex items-center justify-between gap-4 p-4 pb-2">
+ <div className="flex flex-col min-w-0">
+ <h5 className="text-sm text-foreground truncate">Free plan usage</h5>
+ <p className="text-xs text-foreground-lighter truncate">Current billing cycle</p>
+ </div>
+ <div className="flex flex-col items-end gap-1 shrink-0">
+ <UpgradePlanButton
+ source={PLACEMENT}
+ plan="Pro"
+ onClick={() => track('upgrade_cta_clicked', { placement: PLACEMENT })}
+ />
+ </div>
+ </div>
+ <div className="flex flex-col justify-end pb-2 [&>:first-child>*]:border-t-0">
+ {isSuccess
+ ? visibleRows.map(({ config, usageItem }) => (
+ <CompactMetricRow
+ key={config.key}
+ usageItem={usageItem}
+ config={config}
+ orgSlug={organization?.slug ?? '_'}
+ />
+ ))
+ : METRICS.map((config) => <SkeletonMetricRow key={config.key} label={config.label} />)}
+ </div>
+ </div>
+ </li>
+ )
+}
diff --git a/apps/studio/components/interfaces/UserDropdown.tsx b/apps/studio/components/interfaces/UserDropdown.tsx
index d31d90dec39..b4f64927828 100644
--- a/apps/studio/components/interfaces/UserDropdown.tsx
+++ b/apps/studio/components/interfaces/UserDropdown.tsx
@@ -3,6 +3,7 @@ import { FlaskConical, Loader2, ScrollText, Settings } from 'lucide-react'
import { useTheme } from 'next-themes'
import Link from 'next/link'
import { useRouter } from 'next/router'
+import { useState } from 'react'
import {
cn,
DropdownMenu,
@@ -22,7 +23,9 @@ import { ButtonTooltip } from '../ui/ButtonTooltip'
import { useFeaturePreviewModal } from './App/FeaturePreview/FeaturePreviewContext'
import { TimezoneDropdown } from './UserDropdown/TimezoneDropdown'
import { ProfileImage } from '@/components/ui/ProfileImage'
+import { UpgradePlanButton } from '@/components/ui/UpgradePlanButton'
import { useIsFeatureEnabled } from '@/hooks/misc/useIsFeatureEnabled'
+import { useUpgradeCtaExperiment } from '@/hooks/misc/useUpgradeCtaExperiment'
import { IS_PLATFORM } from '@/lib/constants'
import { useProfileNameAndPicture } from '@/lib/profile'
import { useTrack } from '@/lib/telemetry/track'
@@ -45,9 +48,20 @@ export function UserDropdown({
const { toggleFeaturePreviewModal } = useFeaturePreviewModal()
const track = useTrack()
+ const { variant: upgradeCtaVariant } = useUpgradeCtaExperiment()
+ // Per Slack feedback (Jonny): the upgrade CTA is org-scoped, so only show it on routes
+ // where an org is in scope. Excludes /account/*, /organizations, /new, marketing routes, etc.
+ const isOrgScopedRoute =
+ router.pathname.startsWith('/project/') || router.pathname.startsWith('/org/')
+ const showUpgradeCta = upgradeCtaVariant === 'user_dropdown' && isOrgScopedRoute
+
+ const [isOpen, setIsOpen] = useState(false)
+
return (
<DropdownMenu
+ open={isOpen}
onOpenChange={(open) => {
+ setIsOpen(open)
if (open) track('header_user_dropdown_opened')
}}
>
@@ -155,6 +169,22 @@ export function UserDropdown({
</DropdownMenuGroup>
</>
)}
+ {showUpgradeCta && (
+ <>
+ <DropdownMenuSeparator />
+ <div className="p-1">
+ <UpgradePlanButton
+ source="user_dropdown"
+ plan="Pro"
+ className="w-full justify-center"
+ onClick={() => {
+ track('upgrade_cta_clicked', { placement: 'user_dropdown' })
+ setIsOpen(false)
+ }}
+ />
+ </div>
+ </>
+ )}
{IS_PLATFORM && (
<>
<DropdownMenuSeparator />
diff --git a/apps/studio/hooks/misc/useUpgradeCtaExperiment.ts b/apps/studio/hooks/misc/useUpgradeCtaExperiment.ts
new file mode 100644
index 00000000000..23ba7f53d9d
--- /dev/null
+++ b/apps/studio/hooks/misc/useUpgradeCtaExperiment.ts
@@ -0,0 +1,97 @@
+import { IS_PLATFORM, safeLocalStorage, useFeatureFlags, useParams } from 'common'
+import { useEffect, useMemo } from 'react'
+
+import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+import { useTrackExperimentExposure } from '@/hooks/misc/useTrackExperimentExposure'
+import { usePHFlag } from '@/hooks/ui/useFlag'
+
+// PostHog flag key (camelCase, matches other flag naming in the codebase).
+export const UPGRADE_CTA_FLAG_NAME = 'upgradeCtaPlacement'
+
+// snake_case experiment ID so the auto-fired exposure event name matches the
+// `[experiment_id]_experiment_exposed` typed event registered in telemetry-constants.ts.
+const UPGRADE_CTA_EXPERIMENT_ID = 'upgrade_cta_placement'
+
+// localStorage key prefix for the seeded variant (see hook docs). Keyed per org slug
+// because eligibility folds in that org's plan.
+const UPGRADE_CTA_SEED_PREFIX = 'supabase-upgrade-cta-variant-'
+
+export type UpgradeCtaPlacement = 'control' | 'user_dropdown' | 'org_projects_list'
+
+const VALID_VARIANTS: UpgradeCtaPlacement[] = ['control', 'user_dropdown', 'org_projects_list']
+
+/**
+ * Shared experiment state for the upgrade CTA placement test.
+ *
+ * `variant` is the placement to render, and is gated on a confirmed free plan + the
+ * experiment flag — paid users never receive a variant, so the CTA never renders for them.
+ *
+ * First-paint correctness: PostHog flags are fetched async on every load, so the flag
+ * (and therefore the variant) is unknown at first paint. To avoid the CTA popping in
+ * (layout shift) or flashing, we persist the last resolved variant per org and seed from
+ * it synchronously. The seed is used only until the live flag + plan resolve, then the
+ * live value takes over and is re-persisted — so it self-heals if anything changed. A
+ * confirmed paid plan always wins over a stale seed, so the CTA can't flash for paid users.
+ *
+ * Net effect: correct at first paint with no shift/flash on every visit after the first
+ * (the first-ever visit to a given org still resolves async).
+ *
+ * Exposure tracking fires only once confirmed (free-plan + in experiment), so the
+ * experiment cohort stays accurate.
+ */
+export const useUpgradeCtaExperiment = () => {
+ const { slug } = useParams()
+ const { data: organization, isPending: isOrgPending } = useSelectedOrganizationQuery()
+ const flagStore = useFeatureFlags()
+ const flagValue = usePHFlag<UpgradeCtaPlacement | false>(UPGRADE_CTA_FLAG_NAME)
+
+ const flagsLoaded = flagStore.hasLoaded === true
+ const planKnown = !isOrgPending
+ const isFreePlan = organization?.plan?.id === 'free'
+ const isInExperiment =
+ typeof flagValue === 'string' && VALID_VARIANTS.includes(flagValue as UpgradeCtaPlacement)
+
+ // The definitive variant for a confirmed free-plan user in the experiment.
+ const liveVariant = isFreePlan && isInExperiment ? (flagValue as UpgradeCtaPlacement) : undefined
+
+ // Synchronous seed from the last resolved variant for this org. Read via useMemo so it
+ // re-reads when the org slug changes (e.g. navigating between orgs without a remount).
+ const seedKey = `${UPGRADE_CTA_SEED_PREFIX}${slug ?? 'none'}`
+ const seededVariant = useMemo<UpgradeCtaPlacement | null>(() => {
+ const item = safeLocalStorage.getItem(seedKey)
+ if (!item) return null
+ try {
+ const parsed = JSON.parse(item)
+ return VALID_VARIANTS.includes(parsed) ? (parsed as UpgradeCtaPlacement) : null
+ } catch {
+ return null
+ }
+ }, [seedKey])
+
+ let variant: UpgradeCtaPlacement | undefined
+ if (!IS_PLATFORM) {
+ // No billing/plans on self-hosted, so there is nothing to upgrade to — never show.
+ variant = undefined
+ } else if (flagsLoaded && planKnown) {
+ // Fully resolved — source of truth.
+ variant = liveVariant
+ } else if (planKnown && !isFreePlan) {
+ // Confirmed paid — never show, even if a stale seed says otherwise.
+ variant = undefined
+ } else {
+ // Free, or still loading — trust the last known value to avoid a first-paint shift.
+ variant = seededVariant ?? undefined
+ }
+
+ // Persist the last resolved variant once we have a definitive answer, so the next visit
+ // to this org can seed from it. Only matters before the live value resolves, so we don't
+ // need it in component state.
+ useEffect(() => {
+ if (!IS_PLATFORM || !flagsLoaded || !planKnown) return
+ safeLocalStorage.setItem(seedKey, JSON.stringify(liveVariant ?? null))
+ }, [flagsLoaded, planKnown, liveVariant, seedKey])
+
+ useTrackExperimentExposure(UPGRADE_CTA_EXPERIMENT_ID, liveVariant)
+
+ return { isFreePlan, variant }
+}
diff --git a/apps/studio/pages/org/[slug]/index.tsx b/apps/studio/pages/org/[slug]/index.tsx
index 25348beed3b..07955393c69 100644
--- a/apps/studio/pages/org/[slug]/index.tsx
+++ b/apps/studio/pages/org/[slug]/index.tsx
@@ -5,18 +5,22 @@ import { Admonition } from 'ui-patterns'
import { ProjectList } from '@/components/interfaces/Home/ProjectList/ProjectList'
import { HomePageActions } from '@/components/interfaces/HomePageActions'
+import { PlanUsageCard } from '@/components/interfaces/ProjectHome/PlanUsageCard'
import DefaultLayout from '@/components/layouts/DefaultLayout'
import OrganizationLayout from '@/components/layouts/OrganizationLayout'
import { PageLayout } from '@/components/layouts/PageLayout/PageLayout'
import { ScaffoldContainer, ScaffoldSection } from '@/components/layouts/Scaffold'
import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+import { useUpgradeCtaExperiment } from '@/hooks/misc/useUpgradeCtaExperiment'
import type { NextPageWithLayout } from '@/types'
const ProjectsPage: NextPageWithLayout = () => {
const isUserMFAEnabled = useIsMFAEnabled()
const { data: org } = useSelectedOrganizationQuery()
+ const { variant: upgradeCtaVariant } = useUpgradeCtaExperiment()
const disableAccessMfa = org?.organization_requires_mfa && !isUserMFAEnabled
+ const showOrgProjectsListUsageCard = upgradeCtaVariant === 'org_projects_list'
return (
<ScaffoldContainer className="grow flex">
@@ -39,9 +43,18 @@ const ProjectsPage: NextPageWithLayout = () => {
}
/>
) : (
- <div className="flex flex-col gap-y-4">
- <HomePageActions />
- <ProjectList />
+ <div className="flex flex-col gap-y-4 xl:flex-row xl:gap-x-6">
+ <div className="flex flex-col gap-y-4 flex-1 min-w-0">
+ <HomePageActions />
+ <ProjectList />
+ </div>
+ {showOrgProjectsListUsageCard && (
+ <aside className="xl:w-80 xl:shrink-0">
+ <ul className="list-none p-0 m-0">
+ <PlanUsageCard />
+ </ul>
+ </aside>
+ )}
</div>
)}
</ScaffoldSection>
diff --git a/packages/common/telemetry-constants.ts b/packages/common/telemetry-constants.ts
index d000c1e47ee..f90428deb79 100644
--- a/packages/common/telemetry-constants.ts
+++ b/packages/common/telemetry-constants.ts
@@ -3111,6 +3111,40 @@ export interface AccessTokenRemovedEvent {
groups: Omit<TelemetryGroups, 'project'>
}
+/**
+ * User clicked the "Upgrade to Pro" CTA in one of the experiment placement surfaces.
+ * GROWTH experiment: `upgradeCtaPlacement` (user_dropdown / org_projects_list).
+ *
+ * @group Events
+ * @source studio
+ */
+export interface UpgradeCtaClickedEvent {
+ action: 'upgrade_cta_clicked'
+ properties: {
+ placement: 'user_dropdown' | 'org_projects_list'
+ }
+ groups: Omit<TelemetryGroups, 'project'>
+}
+
+/**
+ * User was exposed to the upgrade CTA placement experiment.
+ * Fires once per session per free-plan user enrolled in any variant (including control),
+ * so the conversion analysis has a baseline cohort.
+ *
+ * @group Events
+ * @source studio
+ */
+export interface UpgradeCtaPlacementExperimentExposedEvent {
+ action: 'upgrade_cta_placement_experiment_exposed'
+ properties: {
+ /**
+ * The experiment variant shown to the user
+ */
+ variant: 'control' | 'user_dropdown' | 'org_projects_list'
+ }
+ groups: Omit<TelemetryGroups, 'project'>
+}
+
/**
* User clicked the primary CTA on a resource exhaustion warning banner.
*
@@ -3520,6 +3554,8 @@ export type TelemetryEvent =
| ComputeBadgeUpgradeClickedEvent
| FreeMicroUpgradeBannerDismissedEvent
| FreeMicroUpgradeBannerCtaClickedEvent
+ | UpgradeCtaClickedEvent
+ | UpgradeCtaPlacementExperimentExposedEvent
| AccessTokenCreatedEvent
| AccessTokenRemovedEvent
| ResourceExhaustionBannerUpgradeClickedEvent