Automattic · kangzj · Jun 25, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 25, 2026
@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Stats: Add subscribers hooks.
@@ -21,6 +21,8 @@ const statsHookNames = [
 	'useStatsAppPlanUsage',
 	'useStatsArchives',
 	'useStatsComments',
+	'useStatsSubscribers',
+	'useStatsSubscribersCounts',
 	'useStatsStreak',
 	'useStatsVisits',
 	'useStatsInsights',

@@ -42,6 +42,15 @@ export {
 	type StatsCommentsParams,
 	type StatsCommentsResponse,
 } from './use-stats-comments';
+export {
+	useStatsSubscribers,
+	useStatsSubscribersCounts,
+	type StatsSubscribersCounts,
+	type StatsSubscribersCountsParams,
+	type StatsSubscribersCountsResponse,
+	type StatsSubscribersParams,
+	type StatsSubscribersResponse,
+} from './use-stats-subscribers';
 export {
 	useStatsStreak,
 	type StatsStreakParams,

@@ -0,0 +1,32 @@
+/**
+ * Internal dependencies
+ */
+import {
+	statsSubscribersCountsQuery,
+	statsSubscribersQuery,
+} from '../queries/stats-subscribers-query';
+import { useStatsQuery } from './use-stats-query';
+import type { UseStatsOptions } from './use-stats-report';
+import type { StatsSubscribersCounts } from '../processing/stats';
+import type {
+	StatsSubscribersCountsParams,
+	StatsSubscribersParams,
+} from '../queries/stats-subscribers-query';
+
+export type { StatsSubscribersCounts, StatsSubscribersResponse } from '../processing/stats';
+export type {
+	StatsSubscribersCountsParams,
+	StatsSubscribersParams,
+} from '../queries/stats-subscribers-query';
+export type StatsSubscribersCountsResponse = StatsSubscribersCounts;
+
+export function useStatsSubscribers( params: StatsSubscribersParams, options?: UseStatsOptions ) {
+	return useStatsQuery( statsSubscribersQuery( params ), options );
+}
+
+export function useStatsSubscribersCounts(
+	params?: StatsSubscribersCountsParams,
+	options?: UseStatsOptions
+) {
+	return useStatsQuery( statsSubscribersCountsQuery( params ), options );
+}
@@ -47,6 +47,15 @@ export {
 	type StatsCommentsParams,
 	type StatsCommentsResponse,
 } from './hooks/use-stats-comments';
+export {
+	useStatsSubscribers,
+	useStatsSubscribersCounts,
+	type StatsSubscribersCounts,
+	type StatsSubscribersCountsParams,
+	type StatsSubscribersCountsResponse,
+	type StatsSubscribersParams,
+	type StatsSubscribersResponse,
+} from './hooks/use-stats-subscribers';
 export {
 	useStatsStreak,
 	type StatsStreakParams,
@@ -129,6 +138,9 @@ export type {
 	StatsPostYear,
 	StatsReferrersItem,
 	StatsSearchTermsItem,
+	StatsSubscribersCountsRawResponse,
+	StatsSubscribersDataPoint,
+	StatsSubscribersRawResponse,
 	StatsStreakRawResponse,
 	StatsTagsChildItem,
 	StatsTagsItem,

@@ -0,0 +1,25 @@
+import type {
+	StatsSubscribersCountsRawResponse,
+	StatsSubscribersRawResponse,
+} from '../subscribers';
+
+export const subscribersFixture = {
+	date: '2026-06-25',
+	unit: 'day',
+	fields: [ 'period', 'subscribers', 'subscribers_paid' ],
+	data: [
+		[ '2026-06-24', '10', '2' ],
+		[ '2026-06-25', 12, 3 ],
+	],
+} satisfies StatsSubscribersRawResponse;
+
+export const subscribersCountsFixture = {
+	counts: {
+		total_subscribers: 42,
+		email_subscribers: 31,
+		paid_subscribers: 5,
+		social_followers: 9,
+	},
+} satisfies StatsSubscribersCountsRawResponse;
+
+export const emptySubscribersCountsFixture = {} satisfies StatsSubscribersCountsRawResponse;
@@ -0,0 +1,55 @@
+import { sanitizeStatsSubscribersCountsResponse, sanitizeStatsSubscribersResponse } from '..';
+import {
+	emptySubscribersCountsFixture,
+	subscribersCountsFixture,
+	subscribersFixture,
+} from '../__fixtures__/subscribers';
+
+describe( 'Stats subscribers normalizers', () => {
+	it( 'normalizes raw subscribers matrix rows into time-series data points', () => {
+		const result = sanitizeStatsSubscribersResponse( subscribersFixture );
+
+		expect( result.summary ).toEqual(
+			expect.objectContaining( {
+				subscribers: 22,
+				subscribers_paid: 5,
+				date_start: '2026-06-24T00:00:00+00:00',
+				date_end: '2026-06-25T23:59:59+00:00',
+			} )
+		);
+		expect( result.data ).toEqual( [
+			expect.objectContaining( {
+				time_interval: '2026-06-24',
+				value: 10,
+				subscribers: 10,
+				subscribers_paid: 2,
+				items: [],
+			} ),
+			expect.objectContaining( {
+				time_interval: '2026-06-25',
+				value: 12,
+				subscribers: 12,
+				subscribers_paid: 3,
+				items: [],
+			} ),
+		] );
+	} );
+
+	it( 'normalizes subscribers counts by flattening the raw counts object', () => {
+		expect( sanitizeStatsSubscribersCountsResponse( subscribersCountsFixture ) ).toEqual( {
+			total_subscribers: 42,
+			email_subscribers: 31,
+			paid_subscribers: 5,
+			social_followers: 9,
+		} );
+	} );
+
+	it( 'preserves missing counts as unset fields', () => {
+		expect( sanitizeStatsSubscribersCountsResponse( emptySubscribersCountsFixture ) ).toEqual( {
+			total_subscribers: undefined,
+			email_subscribers: undefined,
+			paid_subscribers: undefined,
+			social_followers: undefined,
+		} );
+	} );
+} );
@@ -21,6 +21,10 @@ export { sanitizeStatsEmailSummaryResponse } from './email-summary';
 export { sanitizeStatsEmailBreakdownResponse } from './email-breakdown';
 export { sanitizeStatsArchivesResponse } from './archives';
 export { sanitizeStatsCommentsResponse } from './comments';
+export {
+	sanitizeStatsSubscribersResponse,
+	sanitizeStatsSubscribersCountsResponse,
+} from './subscribers';
 export { sanitizeStatsStreakResponse } from './streak';
 export { sanitizeStatsTagsResponse } from './tags';
 export type { StatsTopPostsItem } from './top-posts';
@@ -67,6 +71,13 @@ export type {
 	StatsCommentsRawResponse,
 	StatsCommentsResponse,
 } from './comments';
+export type {
+	StatsSubscribersCounts,
+	StatsSubscribersCountsRawResponse,
+	StatsSubscribersDataPoint,
+	StatsSubscribersRawResponse,
+	StatsSubscribersResponse,
+} from './subscribers';
 export type { StatsStreakRawResponse, StatsStreakResponse } from './streak';
 export type { StatsTimeSeriesDataPoint, StatsTimeSeriesReport } from './time-series';
 export type {

@@ -0,0 +1,67 @@
+import { sanitizeStatsTimeSeriesResponse } from './time-series';
+import { coerceStatsRecord } from './utils';
+import type { StatsNormalizedDataPoint, StatsNormalizedReport } from './types';
+import type { StatsQueryParams } from '../../utils/stats-params';
+
+export type StatsSubscribersRawResponse = {
+	date?: string;
+	unit?: string;
+	fields?: string[];
+	data?: Array< Array< string | number | null > >;
+};
+
+export type StatsSubscribersDataPoint = StatsNormalizedDataPoint & {
+	value: number;
+	subscribers?: number;
+	subscribers_paid?: number;
+};
+
+export type StatsSubscribersResponse = StatsNormalizedReport & {
+	data: StatsSubscribersDataPoint[];
+};
+
+export type StatsSubscribersCounts = {
+	total_subscribers?: number;
+	email_subscribers?: number;
+	paid_subscribers?: number;
+	social_followers?: number;
+};
+
+export type StatsSubscribersCountsRawResponse = {
+	counts?: StatsSubscribersCounts;
+};
+
+const countFields = [
+	'total_subscribers',
+	'email_subscribers',
+	'paid_subscribers',
+	'social_followers',
+] as const satisfies ReadonlyArray< keyof StatsSubscribersCounts >;
+
+function normalizeCountValue( value: unknown ) {
+	return typeof value === 'number' ? value : undefined;
+}
+
+export function sanitizeStatsSubscribersResponse(
+	response: StatsSubscribersRawResponse,
+	query?: StatsQueryParams
+): StatsSubscribersResponse;
+export function sanitizeStatsSubscribersResponse(
+	response: unknown,
+	query?: StatsQueryParams
+): StatsSubscribersResponse {
+	return sanitizeStatsTimeSeriesResponse( response, query ) as StatsSubscribersResponse;
+}
+
+export function sanitizeStatsSubscribersCountsResponse(
+	response: StatsSubscribersCountsRawResponse
+): StatsSubscribersCounts;
+export function sanitizeStatsSubscribersCountsResponse(
+	response: unknown
+): StatsSubscribersCounts {
+	const counts = coerceStatsRecord( coerceStatsRecord( response ).counts );
+
+	return Object.fromEntries(
+		countFields.map( field => [ field, normalizeCountValue( counts[ field ] ) ] )
+	) as StatsSubscribersCounts;
+}
@@ -9,6 +9,7 @@ import { statsInsightsQuery } from '../stats-insights-query';
 import { statsLocationsQuery } from '../stats-locations-query';
 import { statsPostQuery } from '../stats-post-query';
 import { statsStreakQuery } from '../stats-streak-query';
+import { statsSubscribersCountsQuery, statsSubscribersQuery } from '../stats-subscribers-query';
 import { statsTagsQuery } from '../stats-tags-query';
 import { statsTopPostsQuery } from '../stats-top-posts-query';
 import { statsUtmQuery } from '../stats-utm-query';
@@ -275,6 +276,62 @@ describe( 'Stats query factories', () => {
 		);
 	} );
 
+	it( 'builds subscribers query keys with Calypso endpoint params and default stat fields', () => {
+		const query = statsSubscribersQuery( {
+			unit: 'week',
+			quantity: 12,
+			date: '2026-06-25',
+		} );
+
+		expect( query.queryKey ).toEqual( [
+			'stats',
+			'subscribers',
+			'1.1',
+			'stats/subscribers',
+			'GET',
+			{
+				unit: 'week',
+				quantity: 12,
+				date: '2026-06-25',
+				stat_fields: 'subscribers,subscribers_paid',
+			},
+			undefined,
+			'subscribers',
+		] );
+	} );
+
+	it( 'preserves explicit subscribers stat fields', () => {
+		const query = statsSubscribersQuery( {
+			unit: 'day',
+			quantity: 30,
+			date: '2026-06-25',
+			stat_fields: 'subscribers',
+		} );
+
+		expect( query.queryKey ).toEqual(
+			expect.arrayContaining( [
+				expect.objectContaining( {
+					stat_fields: 'subscribers',
+				} ),
+			] )
+		);
+	} );
+
+	it( 'builds subscribers counts query keys with a typed sanitizer', () => {
+		const query = statsSubscribersCountsQuery();
+
+		expect( query.queryKey ).toEqual( [
+			'stats',
+			'subscribers-counts',
+			'2',
+			'subscribers/counts',
+			'GET',
+			{},
+			undefined,
+			'subscribersCounts',
+		] );
+	} );
+
 	it( 'sets visits quantity for day ranges', () => {
 		const query = statsVisitsQuery( {
 			from: '2026-06-01',

@@ -27,6 +27,12 @@ export { statsAppDashboardModuleSettingsQuery } from './stats-app-dashboard-modu
 export { statsAppPlanUsageQuery } from './stats-app-plan-usage-query';
 export { statsArchivesQuery } from './stats-archives-query';
 export { statsCommentsQuery, type StatsCommentsParams } from './stats-comments-query';
+export {
+	statsSubscribersCountsQuery,
+	statsSubscribersQuery,
+	type StatsSubscribersCountsParams,
+	type StatsSubscribersParams,
+} from './stats-subscribers-query';
 export { statsStreakQuery } from './stats-streak-query';
 export { statsVisitsQuery } from './stats-visits-query';
 export { statsInsightsQuery } from './stats-insights-query';

@@ -15,11 +15,14 @@ import {
 	sanitizeStatsStreakResponse,
 	sanitizeStatsVisitsResponse,
 	sanitizeStatsTagsResponse,
+	sanitizeStatsTimeSeriesResponse,
 	sanitizeStatsPassthroughResponse,
 	sanitizeStatsPostResponse,
 	sanitizeStatsReferrersResponse,
 	sanitizeStatsSearchTermsResponse,
 	sanitizeStatsSiteResponse,
+	sanitizeStatsSubscribersCountsResponse,
+	sanitizeStatsSubscribersResponse,
 	sanitizeStatsTopAuthorsResponse,
 	sanitizeStatsTopPostsResponse,
 	sanitizeStatsUtmResponse,
@@ -56,6 +59,9 @@ const statsSanitizers = {
 	tags: sanitizeStatsTagsResponse,
 	utm: sanitizeStatsUtmResponse,
 	visits: sanitizeStatsVisitsResponse,
+	timeSeries: sanitizeStatsTimeSeriesResponse,
+	subscribers: sanitizeStatsSubscribersResponse,
+	subscribersCounts: sanitizeStatsSubscribersCountsResponse,
 } satisfies Record< string, StatsSanitizer >;
 
 export type StatsSanitizerKey = keyof typeof statsSanitizers;