From 809c05f8658267a8fcab5dbdaec56b0621f5832f Mon Sep 17 00:00:00 2001
From: Baba-Yoga <emmanuelchukwunyere94@gmail.com>
Date: Thu, 25 Jun 2026 00:46:01 +0000
Subject: [PATCH] feat: add multi-entity management (#562) and subscription
 pause (#563)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue #562 – Multi-entity/brand management:
- src/types/entity.ts: Entity hierarchy types, roles, consolidated invoice, merge/divest results
- src/store/entityStore.ts: EntityService (pure fns) + Zustand store with createEntity,
  mergeEntities, divestitureEntity, computeEntityAnalytics, buildConsolidatedInvoice
- src/screens/EntityManagementScreen.tsx: UI for parent/child entity tree, add/remove,
  merge (acquisition), divest, member role management

Issue #563 – Subscription holiday/vacation pause:
- src/types/pause.ts: PauseState machine, PauseLimits, PauseRecord, PausePreview types
- src/store/pauseStore.ts: ProrationCalculator + PauseService (validatePauseRequest,
  initiatePause, resumePause, expireCredit) + Zustand store; max 2 pauses/year, 7-90 days
- src/screens/PauseSubscriptionScreen.tsx: UI with duration picker, reason selector,
  credit preview, early resume, pause history

Navigation:
- src/navigation/types.ts: EntityManagement and PauseSubscription routes added
- src/navigation/AppNavigator.tsx: lazy screens registered in HomeStack + SettingsStack

Chore:
- .gitignore: add Rust target/, Python __pycache__, jest-results, copy file patterns
---
 .gitignore                              |  24 ++
 src/navigation/AppNavigator.tsx         |  22 ++
 src/navigation/types.ts                 |   2 +
 src/screens/EntityManagementScreen.tsx  | 395 +++++++++++++++++++++
 src/screens/PauseSubscriptionScreen.tsx | 450 ++++++++++++++++++++++++
 src/store/entityStore.ts                | 400 +++++++++++++++++++++
 src/store/pauseStore.ts                 | 255 ++++++++++++++
 src/types/entity.ts                     |  87 +++++
 src/types/pause.ts                      |  65 ++++
 9 files changed, 1700 insertions(+)
 create mode 100644 src/screens/EntityManagementScreen.tsx
 create mode 100644 src/screens/PauseSubscriptionScreen.tsx
 create mode 100644 src/store/entityStore.ts
 create mode 100644 src/store/pauseStore.ts
 create mode 100644 src/types/entity.ts
 create mode 100644 src/types/pause.ts

diff --git a/.gitignore b/.gitignore
index d5d62ee1..87901272 100644
--- a/.gitignore
+++ b/.gitignore
@@ -123,3 +123,27 @@ PR_BODY_SUBSCRIPTION_ADVANCED_SEARCH.md
 PR_CI_Optimizations.md
 WCAG_COMPLIANCE.md
 issue*.json
+
+# Rust build artifacts
+contracts/target/
+target/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+*.so
+
+# Jest test snapshots (all locations)
+**/__snapshots__/**
+jest-results/
+test-results/
+
+# Misc generated
+*.orig
+lib copy.*
+*copy.*
diff --git a/src/navigation/AppNavigator.tsx b/src/navigation/AppNavigator.tsx
index 42d96431..44c4faea 100644
--- a/src/navigation/AppNavigator.tsx
+++ b/src/navigation/AppNavigator.tsx
@@ -80,6 +80,8 @@ const AnalyticsDashboard = lazyScreen(() => import('../../app/screens/AnalyticsD
 const RenewalWorkspaceScreen = lazyScreen(() =>
   import('../../app/screens/RenewalWorkspaceScreen').then((m) => ({ default: m.default }))
 );
+const EntityManagementScreen = lazyScreen(() => import('../screens/EntityManagementScreen'));
+const PauseSubscriptionScreen = lazyScreen(() => import('../screens/PauseSubscriptionScreen'));
 
 const Tab = createBottomTabNavigator<TabParamList>();
 const Stack = createNativeStackNavigator<RootStackParamList>();
@@ -207,6 +209,16 @@ const HomeStack = () => (
       component={RenewalWorkspaceScreen}
       options={{ title: 'Renewal Workspace', headerShown: true }}
     />
+    <Stack.Screen
+      name="EntityManagement"
+      component={EntityManagementScreen}
+      options={{ title: 'Entity Management', headerShown: true }}
+    />
+    <Stack.Screen
+      name="PauseSubscription"
+      component={PauseSubscriptionScreen}
+      options={{ title: 'Pause Subscription', headerShown: true }}
+    />
   </Stack.Navigator>
 );
 
@@ -363,6 +375,16 @@ const SettingsStack = () => (
       component={AnalyticsDashboard}
       options={{ title: 'Analytics Dashboard', headerShown: true }}
     />
+    <Stack.Screen
+      name="EntityManagement"
+      component={EntityManagementScreen}
+      options={{ title: 'Entity Management', headerShown: true }}
+    />
+    <Stack.Screen
+      name="PauseSubscription"
+      component={PauseSubscriptionScreen}
+      options={{ title: 'Pause Subscription', headerShown: true }}
+    />
   </Stack.Navigator>
 );
 
diff --git a/src/navigation/types.ts b/src/navigation/types.ts
index 4bbdeced..b6d144c2 100644
--- a/src/navigation/types.ts
+++ b/src/navigation/types.ts
@@ -49,6 +49,8 @@ export type RootStackParamList = {
   PaymentMethods: undefined;
   AnalyticsDashboard: undefined;
   RenewalWorkspace: { renewalId?: string } | undefined;
+  EntityManagement: undefined;
+  PauseSubscription: { subscriptionId: string };
   NotFound: { reason?: string };
 };
 
diff --git a/src/screens/EntityManagementScreen.tsx b/src/screens/EntityManagementScreen.tsx
new file mode 100644
index 00000000..81bb3b90
--- /dev/null
+++ b/src/screens/EntityManagementScreen.tsx
@@ -0,0 +1,395 @@
+import React, { useMemo, useState } from 'react';
+import { Alert, StyleSheet, Text, TextInput, View } from 'react-native';
+import { Button } from '../components/common/Button';
+import { Card } from '../components/common/Card';
+import { ListScreen } from '../components/common/ScreenTemplates';
+import { useEntityStore } from '../store/entityStore';
+import { Entity, EntityRole, EntityStatus } from '../types/entity';
+import { colors, spacing, typography } from '../utils/constants';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const statusColor = (status: EntityStatus): string => {
+  switch (status) {
+    case EntityStatus.ACTIVE:
+      return colors.success;
+    case EntityStatus.INACTIVE:
+      return colors.warning;
+    case EntityStatus.ACQUIRED:
+    case EntityStatus.DIVESTED:
+      return colors.textSecondary;
+    default:
+      return colors.textSecondary;
+  }
+};
+
+const roleBadge = (role: EntityRole): string => {
+  switch (role) {
+    case EntityRole.GLOBAL_ADMIN:
+      return 'Global Admin';
+    case EntityRole.ENTITY_ADMIN:
+      return 'Admin';
+    default:
+      return 'Viewer';
+  }
+};
+
+// ---------------------------------------------------------------------------
+// AddEntityModal – inline form (no external modal dependency)
+// ---------------------------------------------------------------------------
+
+interface AddEntityFormProps {
+  parentId: string | null;
+  existingCount: number;
+  onAdd: (name: string, currency: string, parentId: string | null) => void;
+  onCancel: () => void;
+}
+
+const AddEntityForm: React.FC<AddEntityFormProps> = ({
+  parentId,
+  existingCount,
+  onAdd,
+  onCancel,
+}) => {
+  const [name, setName] = useState(`Entity ${existingCount + 1}`);
+  const [currency, setCurrency] = useState('USD');
+
+  return (
+    <Card style={styles.formCard}>
+      <Text style={styles.formTitle}>{parentId ? 'Add Subsidiary' : 'Add Holding Entity'}</Text>
+      <Text style={styles.label}>Display Name</Text>
+      <TextInput
+        style={styles.input}
+        value={name}
+        onChangeText={setName}
+        placeholder="Acme Corp"
+        placeholderTextColor={colors.textSecondary}
+        accessibilityLabel="Entity name"
+      />
+      <Text style={styles.label}>Currency (ISO 4217)</Text>
+      <TextInput
+        style={styles.input}
+        value={currency}
+        onChangeText={setCurrency}
+        placeholder="USD"
+        placeholderTextColor={colors.textSecondary}
+        autoCapitalize="characters"
+        maxLength={3}
+        accessibilityLabel="Currency code"
+      />
+      <View style={styles.formActions}>
+        <Button title="Cancel" variant="outline" size="small" onPress={onCancel} />
+        <Button
+          title="Add"
+          size="small"
+          onPress={() => {
+            if (!name.trim()) return;
+            onAdd(name.trim(), currency.trim() || 'USD', parentId);
+          }}
+        />
+      </View>
+    </Card>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Entity card
+// ---------------------------------------------------------------------------
+
+interface EntityCardProps {
+  entity: Entity;
+  allEntities: Entity[];
+  onAddChild: (parentId: string) => void;
+  onRemove: (id: string) => void;
+  onDivest: (id: string) => void;
+}
+
+const EntityCard: React.FC<EntityCardProps> = ({
+  entity,
+  allEntities,
+  onAddChild,
+  onRemove,
+  onDivest,
+}) => {
+  const parent = entity.parentId ? allEntities.find((e) => e.id === entity.parentId) : null;
+  const children = allEntities.filter((e) => entity.childIds.includes(e.id));
+
+  return (
+    <Card style={styles.card}>
+      <View style={styles.cardHeader}>
+        <View>
+          <Text style={styles.cardTitle} accessibilityRole="header">
+            {entity.name}
+          </Text>
+          {entity.legalName ? <Text style={styles.meta}>Legal: {entity.legalName}</Text> : null}
+        </View>
+        <Text style={[styles.statusBadge, { color: statusColor(entity.status) }]}>
+          {entity.status}
+        </Text>
+      </View>
+
+      <Text style={styles.meta}>Currency: {entity.currency}</Text>
+      {entity.taxJurisdiction ? (
+        <Text style={styles.meta}>Jurisdiction: {entity.taxJurisdiction}</Text>
+      ) : null}
+      {parent ? <Text style={styles.meta}>Parent: {parent.name}</Text> : null}
+      {children.length > 0 ? (
+        <Text style={styles.meta}>Subsidiaries: {children.map((c) => c.name).join(', ')}</Text>
+      ) : null}
+      <Text style={styles.meta}>
+        Billing: {entity.consolidatedBilling ? 'Consolidated (parent pays)' : 'Independent'}
+      </Text>
+      <Text style={styles.meta}>Members: {entity.members.length}</Text>
+      {entity.members.length > 0 ? (
+        <View style={styles.memberList}>
+          {entity.members.map((m) => (
+            <Text key={m.userId} style={styles.memberRow}>
+              {m.email} — {roleBadge(m.role)}
+            </Text>
+          ))}
+        </View>
+      ) : null}
+
+      <View style={styles.actions}>
+        <Button
+          title="+ Subsidiary"
+          size="small"
+          variant="outline"
+          onPress={() => onAddChild(entity.id)}
+          accessibilityLabel={`Add subsidiary to ${entity.name}`}
+        />
+        {entity.parentId ? (
+          <Button
+            title="Divest"
+            size="small"
+            variant="outline"
+            onPress={() => onDivest(entity.id)}
+            accessibilityLabel={`Divest ${entity.name} from parent`}
+          />
+        ) : null}
+        <Button
+          title="Remove"
+          size="small"
+          variant="outline"
+          onPress={() => onRemove(entity.id)}
+          accessibilityLabel={`Remove entity ${entity.name}`}
+        />
+      </View>
+    </Card>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Screen
+// ---------------------------------------------------------------------------
+
+const EntityManagementScreen: React.FC = () => {
+  const { entities, addEntity, removeEntity, mergeEntities, divestitureEntity, error } =
+    useEntityStore();
+
+  const [addingForParent, setAddingForParent] = useState<string | null | undefined>(undefined);
+
+  // Show only root-level entities at top, sorted by name
+  const rootEntities = useMemo(
+    () => [...entities.filter((e) => !e.parentId)].sort((a, b) => a.name.localeCompare(b.name)),
+    [entities]
+  );
+
+  const handleAddRoot = () => setAddingForParent(null);
+
+  const handleAddChild = (parentId: string) => setAddingForParent(parentId);
+
+  const handleConfirmAdd = (name: string, currency: string, parentId: string | null) => {
+    addEntity(name, currency, parentId);
+    setAddingForParent(undefined);
+  };
+
+  const handleRemove = (id: string) => {
+    const entity = entities.find((e) => e.id === id);
+    if (!entity) return;
+    Alert.alert('Remove Entity', `Remove "${entity.name}"? This action cannot be undone.`, [
+      { text: 'Cancel', style: 'cancel' },
+      {
+        text: 'Remove',
+        style: 'destructive',
+        onPress: () => removeEntity(id),
+      },
+    ]);
+  };
+
+  const handleDivest = (id: string) => {
+    const entity = entities.find((e) => e.id === id);
+    if (!entity) return;
+    Alert.alert(
+      'Divest Entity',
+      `Detach "${entity.name}" from its parent? It will become a standalone entity.`,
+      [
+        { text: 'Cancel', style: 'cancel' },
+        {
+          text: 'Divest',
+          style: 'destructive',
+          onPress: () => {
+            try {
+              divestitureEntity(id);
+            } catch (e) {
+              Alert.alert('Error', (e as Error).message);
+            }
+          },
+        },
+      ]
+    );
+  };
+
+  const handleMerge = () => {
+    if (entities.length < 2) {
+      Alert.alert('Merge', 'You need at least 2 entities to merge.');
+      return;
+    }
+    // Show first two as an example; production UI would use a picker
+    const [first, second] = entities;
+    Alert.alert('Merge Entities (Acquisition)', `Merge "${second.name}" into "${first.name}"?`, [
+      { text: 'Cancel', style: 'cancel' },
+      {
+        text: 'Merge',
+        style: 'destructive',
+        onPress: () => {
+          try {
+            mergeEntities(first.id, second.id);
+          } catch (e) {
+            Alert.alert('Error', (e as Error).message);
+          }
+        },
+      },
+    ]);
+  };
+
+  // Prepend the inline form as a list item when active
+  const listData: (Entity | 'ADD_FORM')[] = useMemo(
+    () => (addingForParent !== undefined ? ['ADD_FORM', ...rootEntities] : rootEntities),
+    [addingForParent, rootEntities]
+  );
+
+  const renderItem = (item: Entity | 'ADD_FORM') => {
+    if (item === 'ADD_FORM') {
+      return (
+        <AddEntityForm
+          parentId={addingForParent ?? null}
+          existingCount={entities.length}
+          onAdd={handleConfirmAdd}
+          onCancel={() => setAddingForParent(undefined)}
+        />
+      );
+    }
+    return (
+      <EntityCard
+        entity={item}
+        allEntities={entities}
+        onAddChild={handleAddChild}
+        onRemove={handleRemove}
+        onDivest={handleDivest}
+      />
+    );
+  };
+
+  return (
+    <ListScreen
+      title="Entities"
+      subtitle="Holding companies and subsidiaries with consolidated billing"
+      analyticsName="EntityManagement"
+      data={listData}
+      renderItem={renderItem}
+      keyExtractor={(item) => (item === 'ADD_FORM' ? 'add-form' : item.id)}
+      emptyTitle="No entities yet"
+      emptyMessage="Add a holding entity to manage subsidiaries, consolidated invoicing, and cross-entity analytics."
+      emptyActionText="Add entity"
+      onEmptyAction={handleAddRoot}
+      error={error}
+      rightAction={
+        <View style={styles.headerActions}>
+          {entities.length >= 2 ? (
+            <Button title="Merge" size="small" variant="outline" onPress={handleMerge} />
+          ) : null}
+          <Button title="+ Entity" size="small" onPress={handleAddRoot} />
+        </View>
+      }
+      testID="entity-management-screen"
+    />
+  );
+};
+
+const styles = StyleSheet.create({
+  headerActions: {
+    flexDirection: 'row',
+    gap: spacing.sm,
+  },
+  card: {
+    marginBottom: spacing.md,
+  },
+  cardHeader: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'flex-start',
+    marginBottom: spacing.xs,
+  },
+  cardTitle: {
+    ...typography.h3,
+    color: colors.text,
+  },
+  statusBadge: {
+    ...typography.small,
+    textTransform: 'capitalize',
+    fontWeight: '600',
+  },
+  meta: {
+    ...typography.body2,
+    color: colors.textSecondary,
+    marginBottom: spacing.xs,
+  },
+  memberList: {
+    marginTop: spacing.xs,
+    marginBottom: spacing.xs,
+  },
+  memberRow: {
+    ...typography.small,
+    color: colors.textSecondary,
+  },
+  actions: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: spacing.sm,
+    marginTop: spacing.md,
+  },
+  formCard: {
+    marginBottom: spacing.lg,
+    borderColor: colors.primary,
+    borderWidth: 1,
+  },
+  formTitle: {
+    ...typography.h3,
+    color: colors.text,
+    marginBottom: spacing.md,
+  },
+  label: {
+    ...typography.caption,
+    color: colors.textSecondary,
+    marginBottom: spacing.xs,
+  },
+  input: {
+    backgroundColor: colors.surfaceVariant,
+    borderRadius: 8,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    color: colors.text,
+    marginBottom: spacing.md,
+    ...typography.body,
+  },
+  formActions: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    gap: spacing.sm,
+  },
+});
+
+export default EntityManagementScreen;
diff --git a/src/screens/PauseSubscriptionScreen.tsx b/src/screens/PauseSubscriptionScreen.tsx
new file mode 100644
index 00000000..0c081d67
--- /dev/null
+++ b/src/screens/PauseSubscriptionScreen.tsx
@@ -0,0 +1,450 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import { Alert, StyleSheet, Text, TouchableOpacity, View } from 'react-native';
+import type { NativeStackScreenProps } from '@react-navigation/native-stack';
+import { Button } from '../components/common/Button';
+import { Card } from '../components/common/Card';
+import { FormScreen } from '../components/common/ScreenTemplates';
+import { usePauseStore } from '../store/pauseStore';
+import { useSubscriptionStore } from '../store/subscriptionStore';
+import { PauseReason, DEFAULT_PAUSE_LIMITS } from '../types/pause';
+import type { RootStackParamList } from '../navigation/types';
+import { colors, spacing, typography } from '../utils/constants';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Props = NativeStackScreenProps<RootStackParamList, 'PauseSubscription'>;
+
+// ---------------------------------------------------------------------------
+// Duration selector
+// ---------------------------------------------------------------------------
+
+const DURATION_OPTIONS = [7, 14, 30, 60, 90];
+
+interface DurationSelectorProps {
+  selected: number;
+  onSelect: (days: number) => void;
+}
+
+const DurationSelector: React.FC<DurationSelectorProps> = ({ selected, onSelect }) => (
+  <View style={styles.durationRow} accessibilityRole="radiogroup">
+    {DURATION_OPTIONS.map((days) => (
+      <TouchableOpacity
+        key={days}
+        style={[styles.durationChip, selected === days && styles.durationChipActive]}
+        onPress={() => onSelect(days)}
+        accessibilityRole="radio"
+        accessibilityState={{ checked: selected === days }}
+        accessibilityLabel={`${days} days`}>
+        <Text style={[styles.durationChipText, selected === days && styles.durationChipTextActive]}>
+          {days}d
+        </Text>
+      </TouchableOpacity>
+    ))}
+  </View>
+);
+
+// ---------------------------------------------------------------------------
+// Reason selector
+// ---------------------------------------------------------------------------
+
+const REASON_LABELS: Record<PauseReason, string> = {
+  [PauseReason.VACATION]: '🏖  Vacation',
+  [PauseReason.FINANCIAL_HARDSHIP]: '💰  Financial hardship',
+  [PauseReason.TEMPORARY_NEED]: '⏸  Temporary need',
+  [PauseReason.OTHER]: '❓  Other',
+};
+
+interface ReasonSelectorProps {
+  selected: PauseReason;
+  onSelect: (reason: PauseReason) => void;
+}
+
+const ReasonSelector: React.FC<ReasonSelectorProps> = ({ selected, onSelect }) => (
+  <View accessibilityRole="radiogroup">
+    {(Object.values(PauseReason) as PauseReason[]).map((reason) => (
+      <TouchableOpacity
+        key={reason}
+        style={[styles.reasonRow, selected === reason && styles.reasonRowActive]}
+        onPress={() => onSelect(reason)}
+        accessibilityRole="radio"
+        accessibilityState={{ checked: selected === reason }}
+        accessibilityLabel={REASON_LABELS[reason]}>
+        <Text style={[styles.reasonText, selected === reason && styles.reasonTextActive]}>
+          {REASON_LABELS[reason]}
+        </Text>
+      </TouchableOpacity>
+    ))}
+  </View>
+);
+
+// ---------------------------------------------------------------------------
+// Active-pause card
+// ---------------------------------------------------------------------------
+
+interface ActivePauseCardProps {
+  subscriptionName: string;
+  resumeDate: Date;
+  creditRemaining: number;
+  currency: string;
+  onResume: () => void;
+}
+
+const ActivePauseCard: React.FC<ActivePauseCardProps> = ({
+  subscriptionName,
+  resumeDate,
+  creditRemaining,
+  currency,
+  onResume,
+}) => {
+  const daysLeft = Math.max(
+    0,
+    Math.ceil((resumeDate.getTime() - Date.now()) / (1000 * 60 * 60 * 24))
+  );
+
+  return (
+    <Card style={styles.activePauseCard}>
+      <Text style={styles.activePauseTitle} accessibilityRole="header">
+        ⏸ {subscriptionName} is paused
+      </Text>
+      <Text style={styles.meta}>
+        Resumes in {daysLeft} day{daysLeft !== 1 ? 's' : ''} —{' '}
+        {resumeDate.toLocaleDateString(undefined, {
+          month: 'short',
+          day: 'numeric',
+          year: 'numeric',
+        })}
+      </Text>
+      <Text style={styles.meta}>
+        Credit remaining: {currency} {creditRemaining.toFixed(2)}
+      </Text>
+      <View style={styles.actions}>
+        <Button
+          title="Resume Early"
+          onPress={onResume}
+          accessibilityLabel="Resume subscription early"
+        />
+      </View>
+    </Card>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Screen
+// ---------------------------------------------------------------------------
+
+const PauseSubscriptionScreen: React.FC<Props> = ({ route }) => {
+  const subscriptionId = route.params?.subscriptionId;
+
+  const { subscriptions } = useSubscriptionStore();
+  const {
+    pauseSubscription,
+    resumeSubscription,
+    getActivePause,
+    getPauseHistory,
+    previewPause,
+    error,
+  } = usePauseStore();
+
+  const subscription = useMemo(
+    () => subscriptions.find((s) => s.id === subscriptionId),
+    [subscriptions, subscriptionId]
+  );
+
+  const activePause = subscriptionId ? getActivePause(subscriptionId) : undefined;
+  const history = subscriptionId ? getPauseHistory(subscriptionId) : [];
+  const completedPauses = history.filter((r) => r.state !== 'paused');
+
+  const [pauseDays, setPauseDays] = useState(30);
+  const [reason, setReason] = useState<PauseReason>(PauseReason.VACATION);
+
+  const preview = useMemo(() => {
+    if (!subscription) return null;
+    return previewPause(subscription, pauseDays);
+  }, [subscription, pauseDays, previewPause]);
+
+  const validation = useMemo(() => {
+    if (!subscriptionId) return { valid: false, reason: 'No subscription selected.' };
+    const store = usePauseStore.getState();
+    return store.validatePause(subscriptionId, pauseDays);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [subscriptionId, pauseDays]);
+
+  const handlePause = useCallback(() => {
+    if (!subscription) return;
+    if (!validation.valid) {
+      Alert.alert('Cannot pause', validation.reason ?? 'Validation failed.');
+      return;
+    }
+    Alert.alert(
+      'Confirm Pause',
+      `Pause "${subscription.name}" for ${pauseDays} days?\n\nYou'll receive a credit of ${subscription.currency} ${preview?.creditAmount.toFixed(2) ?? '0.00'} for the unused period.`,
+      [
+        { text: 'Cancel', style: 'cancel' },
+        {
+          text: 'Pause',
+          onPress: () => {
+            try {
+              pauseSubscription(subscription, pauseDays, reason, DEFAULT_PAUSE_LIMITS);
+            } catch (e) {
+              Alert.alert('Error', (e as Error).message);
+            }
+          },
+        },
+      ]
+    );
+  }, [subscription, pauseDays, reason, preview, validation, pauseSubscription]);
+
+  const handleResume = useCallback(() => {
+    if (!subscriptionId) return;
+    Alert.alert(
+      'Resume Early',
+      'Resume now? Any unused pause credit will be applied to your next charge.',
+      [
+        { text: 'Cancel', style: 'cancel' },
+        {
+          text: 'Resume',
+          onPress: () => {
+            const result = resumeSubscription(subscriptionId, true);
+            if (!result) Alert.alert('Error', 'Could not resume subscription.');
+          },
+        },
+      ]
+    );
+  }, [subscriptionId, resumeSubscription]);
+
+  if (!subscription) {
+    return (
+      <FormScreen
+        title="Pause Subscription"
+        subtitle="Subscription not found"
+        analyticsName="PauseSubscription"
+        testID="pause-subscription-screen">
+        <Text style={styles.notFound}>Subscription not found.</Text>
+      </FormScreen>
+    );
+  }
+
+  return (
+    <FormScreen
+      title="Pause Subscription"
+      subtitle="Take a break without losing your account history"
+      analyticsName="PauseSubscription"
+      error={error}
+      testID="pause-subscription-screen">
+      {/* Active pause state */}
+      {activePause ? (
+        <ActivePauseCard
+          subscriptionName={subscription.name}
+          resumeDate={new Date(activePause.scheduledResumeAt)}
+          creditRemaining={activePause.creditRemaining}
+          currency={activePause.currency}
+          onResume={handleResume}
+        />
+      ) : (
+        <>
+          {/* Subscription summary */}
+          <Card style={styles.card}>
+            <Text style={styles.sectionTitle}>{subscription.name}</Text>
+            <Text style={styles.meta}>
+              {subscription.currency} {subscription.price.toFixed(2)} / {subscription.billingCycle}
+            </Text>
+            <Text style={styles.meta}>
+              Next billing: {new Date(subscription.nextBillingDate).toLocaleDateString()}
+            </Text>
+          </Card>
+
+          {/* Duration */}
+          <Card style={styles.card}>
+            <Text style={styles.sectionTitle}>Pause Duration</Text>
+            <Text style={styles.meta}>Select how many days to pause (7–90 days)</Text>
+            <DurationSelector selected={pauseDays} onSelect={setPauseDays} />
+          </Card>
+
+          {/* Reason */}
+          <Card style={styles.card}>
+            <Text style={styles.sectionTitle}>Reason</Text>
+            <ReasonSelector selected={reason} onSelect={setReason} />
+          </Card>
+
+          {/* Credit preview */}
+          {preview ? (
+            <Card style={styles.previewCard}>
+              <Text style={styles.sectionTitle}>Credit Preview</Text>
+              <Text style={styles.meta}>
+                You'll receive a credit of{' '}
+                <Text style={styles.highlight}>
+                  {preview.currency} {preview.creditAmount.toFixed(2)}
+                </Text>{' '}
+                for the {pauseDays}-day pause.
+              </Text>
+              <Text style={styles.meta}>
+                Scheduled resume:{' '}
+                {preview.scheduledResumeAt.toLocaleDateString(undefined, {
+                  weekday: 'short',
+                  month: 'short',
+                  day: 'numeric',
+                  year: 'numeric',
+                })}
+              </Text>
+              <Text style={styles.note}>
+                ℹ️ No billing or usage accrual during pause. Data and settings are preserved.
+              </Text>
+              {!validation.valid ? (
+                <Text style={styles.validationError}>{validation.reason}</Text>
+              ) : null}
+            </Card>
+          ) : null}
+
+          <Button
+            title={`Pause for ${pauseDays} Days`}
+            onPress={handlePause}
+            disabled={!validation.valid}
+            accessibilityLabel={`Pause subscription for ${pauseDays} days`}
+          />
+        </>
+      )}
+
+      {/* Pause history */}
+      {completedPauses.length > 0 ? (
+        <Card style={styles.historyCard}>
+          <Text style={styles.sectionTitle}>Pause History (this year)</Text>
+          {completedPauses.map((record) => (
+            <View key={record.id} style={styles.historyRow}>
+              <Text style={styles.meta}>
+                {new Date(record.pausedAt).toLocaleDateString()} →{' '}
+                {record.resumedAt
+                  ? new Date(record.resumedAt).toLocaleDateString()
+                  : new Date(record.scheduledResumeAt).toLocaleDateString()}
+              </Text>
+              <Text style={styles.meta}>
+                Credit: {record.currency} {record.creditAmount.toFixed(2)}
+                {record.creditExpired ? ' (expired)' : ''}
+              </Text>
+            </View>
+          ))}
+          <Text style={styles.limitNote}>
+            {completedPauses.length}/{DEFAULT_PAUSE_LIMITS.maxPausesPerYear} pauses used this year
+          </Text>
+        </Card>
+      ) : null}
+    </FormScreen>
+  );
+};
+
+const styles = StyleSheet.create({
+  card: {
+    marginBottom: spacing.md,
+  },
+  previewCard: {
+    marginBottom: spacing.md,
+    borderColor: colors.primary,
+    borderWidth: 1,
+  },
+  historyCard: {
+    marginTop: spacing.lg,
+    marginBottom: spacing.md,
+  },
+  activePauseCard: {
+    marginBottom: spacing.md,
+    borderColor: colors.warning,
+    borderWidth: 1,
+  },
+  activePauseTitle: {
+    ...typography.h3,
+    color: colors.warning,
+    marginBottom: spacing.sm,
+  },
+  sectionTitle: {
+    ...typography.h3,
+    color: colors.text,
+    marginBottom: spacing.sm,
+  },
+  meta: {
+    ...typography.body2,
+    color: colors.textSecondary,
+    marginBottom: spacing.xs,
+  },
+  highlight: {
+    color: colors.primary,
+    fontWeight: '600',
+  },
+  note: {
+    ...typography.small,
+    color: colors.textSecondary,
+    marginTop: spacing.sm,
+  },
+  validationError: {
+    ...typography.body2,
+    color: colors.error,
+    marginTop: spacing.sm,
+  },
+  actions: {
+    marginTop: spacing.md,
+  },
+  durationRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: spacing.sm,
+    marginTop: spacing.sm,
+  },
+  durationChip: {
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: 20,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.surface,
+  },
+  durationChipActive: {
+    borderColor: colors.primary,
+    backgroundColor: colors.primary,
+  },
+  durationChipText: {
+    ...typography.body2,
+    color: colors.textSecondary,
+  },
+  durationChipTextActive: {
+    color: colors.onPrimary,
+    fontWeight: '600',
+  },
+  reasonRow: {
+    paddingVertical: spacing.sm,
+    paddingHorizontal: spacing.md,
+    borderRadius: 8,
+    marginBottom: spacing.xs,
+    backgroundColor: colors.surface,
+  },
+  reasonRowActive: {
+    backgroundColor: colors.surfaceVariant,
+    borderLeftWidth: 3,
+    borderLeftColor: colors.primary,
+  },
+  reasonText: {
+    ...typography.body2,
+    color: colors.textSecondary,
+  },
+  reasonTextActive: {
+    color: colors.text,
+    fontWeight: '600',
+  },
+  historyRow: {
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+    paddingVertical: spacing.sm,
+  },
+  limitNote: {
+    ...typography.small,
+    color: colors.textSecondary,
+    marginTop: spacing.sm,
+  },
+  notFound: {
+    ...typography.body,
+    color: colors.textSecondary,
+    textAlign: 'center',
+    marginTop: spacing.xl,
+  },
+});
+
+export default PauseSubscriptionScreen;
diff --git a/src/store/entityStore.ts b/src/store/entityStore.ts
new file mode 100644
index 00000000..5d34e0d1
--- /dev/null
+++ b/src/store/entityStore.ts
@@ -0,0 +1,400 @@
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  Entity,
+  EntityAnalytics,
+  EntityMember,
+  EntityMergeResult,
+  EntityDivestitureResult,
+  EntityRole,
+  EntityStatus,
+  ConsolidatedInvoice,
+} from '../types/entity';
+
+const generateId = (): string =>
+  `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+
+// ---------------------------------------------------------------------------
+// EntityService – domain logic (pure functions, no side-effects)
+// ---------------------------------------------------------------------------
+
+export function createEntity(
+  name: string,
+  currency: string,
+  parentId: string | null = null,
+  options: Partial<Entity> = {}
+): Entity {
+  const now = new Date();
+  return {
+    id: generateId(),
+    name,
+    legalName: options.legalName,
+    taxJurisdiction: options.taxJurisdiction,
+    currency,
+    parentId,
+    childIds: [],
+    status: EntityStatus.ACTIVE,
+    members: options.members ?? [],
+    paymentMethodId: options.paymentMethodId,
+    consolidatedBilling: options.consolidatedBilling ?? parentId !== null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function addMember(entity: Entity, member: EntityMember): Entity {
+  if (entity.members.some((m) => m.userId === member.userId)) {
+    throw new Error(`User ${member.userId} is already a member of entity ${entity.id}`);
+  }
+  return { ...entity, members: [...entity.members, member], updatedAt: new Date() };
+}
+
+export function removeMember(entity: Entity, userId: string): Entity {
+  return {
+    ...entity,
+    members: entity.members.filter((m) => m.userId !== userId),
+    updatedAt: new Date(),
+  };
+}
+
+export function updateMemberRole(entity: Entity, userId: string, role: EntityRole): Entity {
+  return {
+    ...entity,
+    members: entity.members.map((m) => (m.userId === userId ? { ...m, role } : m)),
+    updatedAt: new Date(),
+  };
+}
+
+/** Resolve effective role: global admin > entity admin > viewer */
+export function resolveRole(entity: Entity, userId: string): EntityRole | null {
+  const member = entity.members.find((m) => m.userId === userId);
+  return member?.role ?? null;
+}
+
+/**
+ * Build aggregate analytics for an entity and its entire descendant tree.
+ * subscriptionsByEntity is a map of entityId → subscriptions with { price, isActive }.
+ */
+export function computeEntityAnalytics(
+  entity: Entity,
+  allEntities: Entity[],
+  subscriptionsByEntity: Map<string, { price: number; isActive: boolean }[]>
+): EntityAnalytics {
+  const getSubtreeMRR = (eid: string): number => {
+    const subs = subscriptionsByEntity.get(eid) ?? [];
+    const direct = subs.filter((s) => s.isActive).reduce((sum, s) => sum + s.price, 0);
+    const e = allEntities.find((x) => x.id === eid);
+    if (!e) return direct;
+    return direct + e.childIds.reduce((sum, cid) => sum + getSubtreeMRR(cid), 0);
+  };
+
+  const allSubs = subscriptionsByEntity.get(entity.id) ?? [];
+  const childBreakdown = entity.childIds.map((cid) => {
+    const child = allEntities.find((x) => x.id === cid);
+    return { entityId: cid, name: child?.name ?? cid, mrr: getSubtreeMRR(cid) };
+  });
+
+  return {
+    entityId: entity.id,
+    totalMRR: getSubtreeMRR(entity.id),
+    totalSubscriptions: allSubs.length,
+    activeSubscriptions: allSubs.filter((s) => s.isActive).length,
+    churnedThisMonth: 0, // Requires historical data; UI can extend this
+    currency: entity.currency,
+    childBreakdown,
+  };
+}
+
+/** Merge absorbedId into survivingId (entity acquisition edge case) */
+export function mergeEntities(
+  entities: Entity[],
+  survivingId: string,
+  absorbedId: string
+): { entities: Entity[]; result: EntityMergeResult } {
+  const surviving = entities.find((e) => e.id === survivingId);
+  const absorbed = entities.find((e) => e.id === absorbedId);
+  if (!surviving || !absorbed) throw new Error('Entity not found for merge');
+
+  const migratedMembers = absorbed.members.length;
+  const mergedMembers = [
+    ...surviving.members,
+    ...absorbed.members.filter((m) => !surviving.members.some((sm) => sm.userId === m.userId)),
+  ];
+
+  const updatedSurviving: Entity = {
+    ...surviving,
+    members: mergedMembers,
+    childIds: [...surviving.childIds, ...absorbed.childIds],
+    updatedAt: new Date(),
+  };
+
+  // Re-parent absorbed children
+  const updatedEntities = entities
+    .filter((e) => e.id !== absorbedId)
+    .map((e) => {
+      if (absorbed.childIds.includes(e.id)) return { ...e, parentId: survivingId };
+      if (e.id === survivingId) return updatedSurviving;
+      // Remove absorbed from parent's childIds
+      if (e.childIds.includes(absorbedId)) {
+        return {
+          ...e,
+          childIds: e.childIds.filter((c) => c !== absorbedId),
+          updatedAt: new Date(),
+        };
+      }
+      return e;
+    });
+
+  return {
+    entities: updatedEntities,
+    result: {
+      survivingEntityId: survivingId,
+      absorbedEntityId: absorbedId,
+      migratedSubscriptions: 0,
+      migratedMembers,
+    },
+  };
+}
+
+/** Detach an entity from its parent (divestiture edge case) */
+export function divestitureEntity(
+  entities: Entity[],
+  entityId: string
+): { entities: Entity[]; result: EntityDivestitureResult } {
+  const entity = entities.find((e) => e.id === entityId);
+  if (!entity) throw new Error('Entity not found for divestiture');
+  if (!entity.parentId) throw new Error('Entity has no parent to divest from');
+
+  const formerParentId = entity.parentId;
+  const updatedEntities = entities.map((e) => {
+    if (e.id === entityId)
+      return { ...e, parentId: null, consolidatedBilling: false, updatedAt: new Date() };
+    if (e.id === formerParentId) {
+      return { ...e, childIds: e.childIds.filter((c) => c !== entityId), updatedAt: new Date() };
+    }
+    return e;
+  });
+
+  return {
+    entities: updatedEntities,
+    result: { detachedEntityId: entityId, formerParentId, migratedSubscriptions: 0 },
+  };
+}
+
+/** Generate a consolidated invoice for all subscriptions under a root entity */
+export function buildConsolidatedInvoice(
+  rootEntity: Entity,
+  allEntities: Entity[],
+  subscriptionsByEntity: Map<
+    string,
+    { id: string; name: string; price: number; currency: string }[]
+  >
+): ConsolidatedInvoice {
+  const lineItems: ConsolidatedInvoice['lineItems'] = [];
+
+  const collectLineItems = (eid: string) => {
+    const entity = allEntities.find((e) => e.id === eid);
+    if (!entity) return;
+    const subs = subscriptionsByEntity.get(eid) ?? [];
+    subs.forEach((s) =>
+      lineItems.push({
+        entityId: eid,
+        entityName: entity.name,
+        subscriptionId: s.id,
+        subscriptionName: s.name,
+        amount: s.price,
+        currency: s.currency,
+      })
+    );
+    entity.childIds.forEach(collectLineItems);
+  };
+
+  collectLineItems(rootEntity.id);
+
+  const totalAmount = lineItems.reduce((sum, item) => sum + item.amount, 0);
+  const now = new Date();
+  const periodStart = new Date(now.getFullYear(), now.getMonth(), 1);
+  const periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+
+  return {
+    id: generateId(),
+    rootEntityId: rootEntity.id,
+    periodStart,
+    periodEnd,
+    lineItems,
+    totalAmount,
+    currency: rootEntity.currency,
+    createdAt: now,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Zustand Store
+// ---------------------------------------------------------------------------
+
+interface EntityState {
+  entities: Entity[];
+  selectedEntityId: string | null;
+  isLoading: boolean;
+  error: string | null;
+
+  addEntity: (
+    name: string,
+    currency: string,
+    parentId?: string | null,
+    options?: Partial<Entity>
+  ) => Entity;
+  updateEntity: (
+    id: string,
+    updates: Partial<
+      Pick<
+        Entity,
+        | 'name'
+        | 'legalName'
+        | 'taxJurisdiction'
+        | 'currency'
+        | 'paymentMethodId'
+        | 'consolidatedBilling'
+        | 'status'
+      >
+    >
+  ) => void;
+  removeEntity: (id: string) => void;
+  addEntityMember: (entityId: string, member: EntityMember) => void;
+  removeEntityMember: (entityId: string, userId: string) => void;
+  updateEntityMemberRole: (entityId: string, userId: string, role: EntityRole) => void;
+  mergeEntities: (survivingId: string, absorbedId: string) => EntityMergeResult;
+  divestitureEntity: (entityId: string) => EntityDivestitureResult;
+  getAnalytics: (
+    entityId: string,
+    subscriptionsByEntity: Map<string, { price: number; isActive: boolean }[]>
+  ) => EntityAnalytics | null;
+  buildInvoice: (
+    rootEntityId: string,
+    subscriptionsByEntity: Map<
+      string,
+      { id: string; name: string; price: number; currency: string }[]
+    >
+  ) => ConsolidatedInvoice | null;
+  selectEntity: (id: string | null) => void;
+}
+
+export const useEntityStore = create<EntityState>()(
+  persist(
+    (set, get) => ({
+      entities: [],
+      selectedEntityId: null,
+      isLoading: false,
+      error: null,
+
+      addEntity: (name, currency, parentId = null, options = {}) => {
+        const entity = createEntity(name, currency, parentId, options);
+        set((state) => {
+          const updatedEntities = [...state.entities, entity].map((e) => {
+            if (e.id === parentId) {
+              return { ...e, childIds: [...e.childIds, entity.id], updatedAt: new Date() };
+            }
+            return e;
+          });
+          return { entities: updatedEntities, error: null };
+        });
+        return entity;
+      },
+
+      updateEntity: (id, updates) => {
+        set((state) => ({
+          entities: state.entities.map((e) =>
+            e.id === id ? { ...e, ...updates, updatedAt: new Date() } : e
+          ),
+          error: null,
+        }));
+      },
+
+      removeEntity: (id) => {
+        set((state) => {
+          const entity = state.entities.find((e) => e.id === id);
+          const updated = state.entities
+            .filter((e) => e.id !== id)
+            .map((e) => {
+              if (entity?.parentId && e.id === entity.parentId) {
+                return { ...e, childIds: e.childIds.filter((c) => c !== id) };
+              }
+              return e;
+            });
+          return {
+            entities: updated,
+            selectedEntityId: state.selectedEntityId === id ? null : state.selectedEntityId,
+          };
+        });
+      },
+
+      addEntityMember: (entityId, member) => {
+        try {
+          set((state) => ({
+            entities: state.entities.map((e) => (e.id === entityId ? addMember(e, member) : e)),
+            error: null,
+          }));
+        } catch (err) {
+          set({ error: (err as Error).message });
+        }
+      },
+
+      removeEntityMember: (entityId, userId) => {
+        set((state) => ({
+          entities: state.entities.map((e) => (e.id === entityId ? removeMember(e, userId) : e)),
+        }));
+      },
+
+      updateEntityMemberRole: (entityId, userId, role) => {
+        set((state) => ({
+          entities: state.entities.map((e) =>
+            e.id === entityId ? updateMemberRole(e, userId, role) : e
+          ),
+        }));
+      },
+
+      mergeEntities: (survivingId, absorbedId) => {
+        try {
+          const { entities, result } = mergeEntities(get().entities, survivingId, absorbedId);
+          set({ entities, error: null });
+          return result;
+        } catch (err) {
+          set({ error: (err as Error).message });
+          throw err;
+        }
+      },
+
+      divestitureEntity: (entityId) => {
+        try {
+          const { entities, result } = divestitureEntity(get().entities, entityId);
+          set({ entities, error: null });
+          return result;
+        } catch (err) {
+          set({ error: (err as Error).message });
+          throw err;
+        }
+      },
+
+      getAnalytics: (entityId, subscriptionsByEntity) => {
+        const all = get().entities;
+        const entity = all.find((e) => e.id === entityId);
+        if (!entity) return null;
+        return computeEntityAnalytics(entity, all, subscriptionsByEntity);
+      },
+
+      buildInvoice: (rootEntityId, subscriptionsByEntity) => {
+        const all = get().entities;
+        const root = all.find((e) => e.id === rootEntityId);
+        if (!root) return null;
+        return buildConsolidatedInvoice(root, all, subscriptionsByEntity);
+      },
+
+      selectEntity: (id) => set({ selectedEntityId: id }),
+    }),
+    {
+      name: 'subtrackr-entities',
+      storage: createJSONStorage(() => AsyncStorage),
+    }
+  )
+);
diff --git a/src/store/pauseStore.ts b/src/store/pauseStore.ts
new file mode 100644
index 00000000..fb98b293
--- /dev/null
+++ b/src/store/pauseStore.ts
@@ -0,0 +1,255 @@
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  PauseRecord,
+  PauseState,
+  PauseReason,
+  PauseLimits,
+  PauseValidationResult,
+  PausePreview,
+  DEFAULT_PAUSE_LIMITS,
+} from '../types/pause';
+import { Subscription } from '../types/subscription';
+import { getPeriodDays } from '../utils/proration';
+
+const generateId = (): string =>
+  `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+
+// ---------------------------------------------------------------------------
+// ProrationCalculator – pure credit calculation for pause
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate credit for pausing: credit = (pauseDays / periodDays) * monthlyPrice
+ */
+export function calculatePauseCredit(subscription: Subscription, pauseDays: number): number {
+  const periodDays = getPeriodDays(subscription.billingCycle);
+  const credit = (pauseDays / periodDays) * subscription.price;
+  return Math.round(credit * 100) / 100;
+}
+
+/**
+ * Calculate remaining credit when user resumes early.
+ * Consumed credit = (daysUsed / totalPauseDays) * originalCredit
+ */
+export function calculateEarlyResumeCredit(record: PauseRecord): number {
+  const now = new Date();
+  const scheduledResume = new Date(record.scheduledResumeAt);
+  const pausedAt = new Date(record.pausedAt);
+
+  const totalPauseDays = Math.max(
+    1,
+    Math.ceil((scheduledResume.getTime() - pausedAt.getTime()) / (1000 * 60 * 60 * 24))
+  );
+  const daysElapsed = Math.max(
+    0,
+    Math.ceil((now.getTime() - pausedAt.getTime()) / (1000 * 60 * 60 * 24))
+  );
+  const daysRemaining = Math.max(0, totalPauseDays - daysElapsed);
+  const remainingCredit = (daysRemaining / totalPauseDays) * record.creditAmount;
+  return Math.round(remainingCredit * 100) / 100;
+}
+
+// ---------------------------------------------------------------------------
+// PauseService – validation and state machine
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a pause request against configured limits.
+ */
+export function validatePauseRequest(
+  subscriptionId: string,
+  pauseDays: number,
+  existingRecords: PauseRecord[],
+  limits: PauseLimits = DEFAULT_PAUSE_LIMITS
+): PauseValidationResult {
+  if (pauseDays < limits.minDays) {
+    return { valid: false, reason: `Minimum pause duration is ${limits.minDays} days.` };
+  }
+  if (pauseDays > limits.maxDays) {
+    return { valid: false, reason: `Maximum pause duration is ${limits.maxDays} days.` };
+  }
+
+  // Count pauses for this subscription in the current calendar year
+  const yearStart = new Date(new Date().getFullYear(), 0, 1);
+  const pausesThisYear = existingRecords.filter(
+    (r) =>
+      r.subscriptionId === subscriptionId &&
+      r.state !== PauseState.ACTIVE && // completed pauses
+      new Date(r.pausedAt) >= yearStart
+  ).length;
+
+  // Also check if there's an active pause
+  const activePause = existingRecords.find(
+    (r) => r.subscriptionId === subscriptionId && r.state === PauseState.PAUSED
+  );
+  if (activePause) {
+    return { valid: false, reason: 'This subscription is already paused.' };
+  }
+
+  if (pausesThisYear >= limits.maxPausesPerYear) {
+    return {
+      valid: false,
+      reason: `Maximum of ${limits.maxPausesPerYear} pauses per year reached.`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Preview what credit a pause would generate before confirming.
+ */
+export function previewPause(subscription: Subscription, pauseDays: number): PausePreview {
+  const scheduledResumeAt = new Date(Date.now() + pauseDays * 24 * 60 * 60 * 1000);
+  const creditAmount = calculatePauseCredit(subscription, pauseDays);
+
+  return {
+    subscriptionId: subscription.id,
+    pauseDays,
+    creditAmount,
+    currency: subscription.currency,
+    scheduledResumeAt,
+    earlyResumeCredit: creditAmount, // Full credit available before any time passes
+  };
+}
+
+/**
+ * Initiate a pause – returns a new PauseRecord.
+ * Edge case: if pause overlaps a renewal date, credit is still calculated from
+ * the current period price; the billing engine must skip renewal while paused.
+ */
+export function initiatePause(
+  subscription: Subscription,
+  pauseDays: number,
+  reason: PauseReason,
+  note?: string
+): PauseRecord {
+  const creditAmount = calculatePauseCredit(subscription, pauseDays);
+  const now = new Date();
+  const scheduledResumeAt = new Date(now.getTime() + pauseDays * 24 * 60 * 60 * 1000);
+
+  return {
+    id: generateId(),
+    subscriptionId: subscription.id,
+    state: PauseState.PAUSED,
+    reason,
+    note,
+    pausedAt: now,
+    scheduledResumeAt,
+    creditAmount,
+    currency: subscription.currency,
+    creditRemaining: creditAmount,
+    creditExpired: false,
+    creditExpiryDays: 90,
+  };
+}
+
+/**
+ * Resume a pause (early or automatic).
+ * Returns updated record with consumed credit if early.
+ */
+export function resumePause(record: PauseRecord, early = false): PauseRecord {
+  const now = new Date();
+  const earlyCredit = early ? calculateEarlyResumeCredit(record) : 0;
+  return {
+    ...record,
+    state: PauseState.ACTIVE,
+    resumedAt: now,
+    creditRemaining: earlyCredit,
+  };
+}
+
+/**
+ * Expire credit when subscription is cancelled after a pause.
+ */
+export function expireCredit(record: PauseRecord): PauseRecord {
+  return { ...record, creditExpired: true, creditRemaining: 0 };
+}
+
+// ---------------------------------------------------------------------------
+// Zustand Store
+// ---------------------------------------------------------------------------
+
+interface PauseState2 {
+  records: PauseRecord[];
+  isLoading: boolean;
+  error: string | null;
+
+  pauseSubscription: (
+    subscription: Subscription,
+    pauseDays: number,
+    reason: PauseReason,
+    limits?: PauseLimits,
+    note?: string
+  ) => PauseRecord;
+  resumeSubscription: (subscriptionId: string, early?: boolean) => PauseRecord | null;
+  expireCreditForSubscription: (subscriptionId: string) => void;
+  getActivePause: (subscriptionId: string) => PauseRecord | undefined;
+  getPauseHistory: (subscriptionId: string) => PauseRecord[];
+  validatePause: (
+    subscriptionId: string,
+    pauseDays: number,
+    limits?: PauseLimits
+  ) => PauseValidationResult;
+  previewPause: (subscription: Subscription, pauseDays: number) => PausePreview;
+}
+
+export const usePauseStore = create<PauseState2>()(
+  persist(
+    (set, get) => ({
+      records: [],
+      isLoading: false,
+      error: null,
+
+      pauseSubscription: (subscription, pauseDays, reason, limits, note) => {
+        const validation = validatePauseRequest(subscription.id, pauseDays, get().records, limits);
+        if (!validation.valid) throw new Error(validation.reason);
+
+        const record = initiatePause(subscription, pauseDays, reason, note);
+        set((state) => ({ records: [...state.records, record], error: null }));
+        return record;
+      },
+
+      resumeSubscription: (subscriptionId, early = false) => {
+        const active = get().records.find(
+          (r) => r.subscriptionId === subscriptionId && r.state === PauseState.PAUSED
+        );
+        if (!active) return null;
+
+        const resumed = resumePause(active, early);
+        set((state) => ({
+          records: state.records.map((r) => (r.id === active.id ? resumed : r)),
+          error: null,
+        }));
+        return resumed;
+      },
+
+      expireCreditForSubscription: (subscriptionId) => {
+        set((state) => ({
+          records: state.records.map((r) =>
+            r.subscriptionId === subscriptionId && !r.creditExpired ? expireCredit(r) : r
+          ),
+        }));
+      },
+
+      getActivePause: (subscriptionId) =>
+        get().records.find(
+          (r) => r.subscriptionId === subscriptionId && r.state === PauseState.PAUSED
+        ),
+
+      getPauseHistory: (subscriptionId) =>
+        get().records.filter((r) => r.subscriptionId === subscriptionId),
+
+      validatePause: (subscriptionId, pauseDays, limits) =>
+        validatePauseRequest(subscriptionId, pauseDays, get().records, limits),
+
+      previewPause: (subscription, pauseDays) => previewPause(subscription, pauseDays),
+    }),
+    {
+      name: 'subtrackr-pauses',
+      storage: createJSONStorage(() => AsyncStorage),
+    }
+  )
+);
diff --git a/src/types/entity.ts b/src/types/entity.ts
new file mode 100644
index 00000000..5c97dba2
--- /dev/null
+++ b/src/types/entity.ts
@@ -0,0 +1,87 @@
+/** Multi-entity / brand management types (Issue #562) */
+
+export enum EntityRole {
+  GLOBAL_ADMIN = 'global_admin',
+  ENTITY_ADMIN = 'entity_admin',
+  VIEWER = 'viewer',
+}
+
+export enum EntityStatus {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  ACQUIRED = 'acquired',
+  DIVESTED = 'divested',
+}
+
+export interface EntityMember {
+  userId: string;
+  email: string;
+  role: EntityRole;
+  entityId: string;
+}
+
+export interface Entity {
+  id: string;
+  name: string;
+  /** Legal / registered name (may differ from display name) */
+  legalName?: string;
+  /** Tax jurisdiction for consolidated reporting */
+  taxJurisdiction?: string;
+  /** ISO 4217 currency for this entity's billing */
+  currency: string;
+  parentId: string | null;
+  childIds: string[];
+  status: EntityStatus;
+  members: EntityMember[];
+  /** Payment method shared from parent, or entity-specific */
+  paymentMethodId?: string;
+  /** If true, parent account pays all subscriptions for this entity */
+  consolidatedBilling: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Aggregate stats rolled up across an entity and all descendants */
+export interface EntityAnalytics {
+  entityId: string;
+  totalMRR: number;
+  totalSubscriptions: number;
+  activeSubscriptions: number;
+  churnedThisMonth: number;
+  currency: string;
+  /** MRR broken down by direct children */
+  childBreakdown: { entityId: string; name: string; mrr: number }[];
+}
+
+/** Result of merging two entity hierarchies (acquisition) */
+export interface EntityMergeResult {
+  survivingEntityId: string;
+  absorbedEntityId: string;
+  migratedSubscriptions: number;
+  migratedMembers: number;
+}
+
+/** Result of splitting an entity out of a hierarchy (divestiture) */
+export interface EntityDivestitureResult {
+  detachedEntityId: string;
+  formerParentId: string;
+  migratedSubscriptions: number;
+}
+
+export interface ConsolidatedInvoice {
+  id: string;
+  rootEntityId: string;
+  periodStart: Date;
+  periodEnd: Date;
+  lineItems: {
+    entityId: string;
+    entityName: string;
+    subscriptionId: string;
+    subscriptionName: string;
+    amount: number;
+    currency: string;
+  }[];
+  totalAmount: number;
+  currency: string;
+  createdAt: Date;
+}
diff --git a/src/types/pause.ts b/src/types/pause.ts
new file mode 100644
index 00000000..75824584
--- /dev/null
+++ b/src/types/pause.ts
@@ -0,0 +1,65 @@
+/** Subscription pause / vacation types (Issue #563) */
+
+export enum PauseState {
+  ACTIVE = 'active',
+  PAUSED = 'paused',
+  RESUMING = 'resuming',
+}
+
+export enum PauseReason {
+  VACATION = 'vacation',
+  FINANCIAL_HARDSHIP = 'financial_hardship',
+  TEMPORARY_NEED = 'temporary_need',
+  OTHER = 'other',
+}
+
+/** Min/max durations and per-year cap are configurable per plan */
+export interface PauseLimits {
+  minDays: number; // default 7
+  maxDays: number; // default 90
+  maxPausesPerYear: number; // default 2
+}
+
+export const DEFAULT_PAUSE_LIMITS: PauseLimits = {
+  minDays: 7,
+  maxDays: 90,
+  maxPausesPerYear: 2,
+};
+
+export interface PauseRecord {
+  id: string;
+  subscriptionId: string;
+  state: PauseState;
+  reason: PauseReason;
+  /** User-supplied note */
+  note?: string;
+  pausedAt: Date;
+  /** Scheduled resume date when pause was initiated */
+  scheduledResumeAt: Date;
+  /** Actual resume date (set on early/automatic resume) */
+  resumedAt?: Date;
+  /** Prorated credit issued for unused period, in subscription currency */
+  creditAmount: number;
+  currency: string;
+  /** Credit remaining after early-resume consumption */
+  creditRemaining: number;
+  /** True once credit has been fully consumed or subscription cancelled */
+  creditExpired: boolean;
+  /** Days credit expires after resume (if subscription is cancelled after pause) */
+  creditExpiryDays: number;
+}
+
+export interface PauseValidationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+export interface PausePreview {
+  subscriptionId: string;
+  pauseDays: number;
+  creditAmount: number;
+  currency: string;
+  scheduledResumeAt: Date;
+  /** Amount that would be credited back on early resume */
+  earlyResumeCredit: number;
+}