From 6380c840a3a44ce01628c5af6ad786a98759a351 Mon Sep 17 00:00:00 2001
From: dee-john <johnezekiel376@gmail.com>
Date: Thu, 28 May 2026 15:10:29 +0100
Subject: [PATCH 1/2] feat(import): CSV column mapping, progress/rollback,
 Stripe/Chargebee import helpers, tests

---
 backend/services/importService.ts        |  89 ++++++++
 backend/services/index.ts                |   1 +
 src/screens/ImportScreen.tsx             | 247 +++++++++++++++++++----
 src/utils/__tests__/importExport.test.ts |  57 ++++++
 4 files changed, 352 insertions(+), 42 deletions(-)
 create mode 100644 backend/services/importService.ts

diff --git a/backend/services/importService.ts b/backend/services/importService.ts
new file mode 100644
index 0000000..2d447ab
--- /dev/null
+++ b/backend/services/importService.ts
@@ -0,0 +1,89 @@
+/**
+ * Lightweight import helpers for server-side import from external platforms
+ * Exposes functions to fetch subscriptions from Stripe and Chargebee and
+ * normalize them to the internal SubscriptionInput shape.
+ */
+import https from 'https';
+
+export interface SubscriptionInput {
+  id?: string;
+  name: string;
+  description?: string;
+  category: string;
+  price: number;
+  currency: string;
+  billingCycle: string;
+  nextBillingDate: string;
+}
+
+function fetchJson(url: string, headers: Record<string, string> = {}): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { headers }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          resolve(parsed);
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+export async function fetchStripeSubscriptions(stripeApiKey: string): Promise<SubscriptionInput[]> {
+  if (!stripeApiKey) throw new Error('Missing Stripe API key');
+
+  // Stripe list subscriptions endpoint (simple, may need pagination in real use)
+  const url = 'https://api.stripe.com/v1/subscriptions?limit=100';
+  const auth = 'Basic ' + Buffer.from(`${stripeApiKey}:`).toString('base64');
+
+  const data = await fetchJson(url, { Authorization: auth });
+
+  const items = data.data || [];
+
+  return items.map((s: any) => ({
+    id: s.id,
+    name: s.plan?.nickname || s.plan?.product || s.id,
+    description: s.description || '',
+    category: 'imported',
+    price: (s.plan?.amount || 0) / 100,
+    currency: (s.plan?.currency || 'USD').toUpperCase(),
+    billingCycle: s.plan?.interval || 'monthly',
+    nextBillingDate: s.current_period_end ? new Date(s.current_period_end * 1000).toISOString() : new Date().toISOString(),
+  }));
+}
+
+export async function fetchChargebeeSubscriptions(site: string, apiKey: string): Promise<SubscriptionInput[]> {
+  if (!site || !apiKey) throw new Error('Missing Chargebee site or API key');
+
+  const url = `https://${site}.chargebee.com/api/v2/subscriptions`;
+  const auth = 'Basic ' + Buffer.from(`${apiKey}:`).toString('base64');
+
+  const data = await fetchJson(url + '?limit=100', { Authorization: auth });
+
+  const list = data.list || [];
+
+  return list.map((entry: any) => {
+    const s = entry.subscription || entry;
+    return {
+      id: s.id,
+      name: s.plan_id || s.id,
+      description: s.plan_description || '',
+      category: 'imported',
+      price: Number(s.amount || 0) / 100,
+      currency: (s.currency_code || 'USD').toUpperCase(),
+      billingCycle: s.billing_period_unit || 'monthly',
+      nextBillingDate: s.next_billing_at ? new Date(s.next_billing_at * 1000).toISOString() : new Date().toISOString(),
+    };
+  });
+}
+
+export default {
+  fetchStripeSubscriptions,
+  fetchChargebeeSubscriptions,
+};
diff --git a/backend/services/index.ts b/backend/services/index.ts
index a1919f0..ddee1e7 100644
--- a/backend/services/index.ts
+++ b/backend/services/index.ts
@@ -40,6 +40,7 @@ export {
   SubscriptionEventStore,
   subscriptionEventStore,
 } from './subscriptionEventStore';
+export { fetchStripeSubscriptions, fetchChargebeeSubscriptions } from './importService';
 export type {
   SubscriptionEvent,
   SubscriptionEventPage,
diff --git a/src/screens/ImportScreen.tsx b/src/screens/ImportScreen.tsx
index c09b3ae..b349340 100644
--- a/src/screens/ImportScreen.tsx
+++ b/src/screens/ImportScreen.tsx
@@ -25,6 +25,7 @@ import {
   getCSVTemplate,
   getJSONTemplate,
   detectFormat,
+  CSV_COLUMN_MAPPING,
   ImportMode,
   ImportResult,
   ValidationResult,
@@ -45,6 +46,10 @@ const ImportScreen: React.FC = () => {
   const [showHistory, setShowHistory] = useState(false);
   const [importHistory, setImportHistory] = useState<ImportHistoryEntry[]>([]);
   const [showTemplateModal, setShowTemplateModal] = useState(false);
+  const [showMappingModal, setShowMappingModal] = useState(false);
+  const [detectedHeaders, setDetectedHeaders] = useState<string[]>([]);
+  const [columnMapping, setColumnMapping] = useState<Record<string, keyof SubscriptionInput | ''>>({});
+  const [progress, setProgress] = useState<{ current: number; total: number; message?: string } | null>(null);
 
   const handleImport = useCallback(async () => {
     if (!importText.trim()) {
@@ -61,7 +66,19 @@ const ImportScreen: React.FC = () => {
       let parsedData: SubscriptionInput[];
 
       if (format === 'csv') {
-        parsedData = parseCSV(importText);
+        // Detect headers for optional mapping
+        const firstLine = importText.split(/\r?\n/).find((l) => l && l.trim());
+        if (firstLine) {
+          const rawHeaders = firstLine.split(',').map((h) => h.replace(/^\"|\"$/g, '').trim());
+          setDetectedHeaders(rawHeaders);
+        }
+
+        // If a mapping exists, transform CSV using mapping, else use parseCSV fallback
+        if (Object.keys(columnMapping).length > 0) {
+          parsedData = parseCSVWithMapping(importText, columnMapping);
+        } else {
+          parsedData = parseCSV(importText);
+        }
       } else if (format === 'json') {
         parsedData = parseJSON(importText);
       } else {
@@ -110,53 +127,149 @@ const ImportScreen: React.FC = () => {
     }
   }, [importText, importMode]);
 
+  // Simple CSV line parser (handles quoted fields)
+  function parseLine(line: string): string[] {
+    const result: string[] = [];
+    let current = '';
+    let inQuotes = false;
+
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i];
+      if (char === '"') {
+        if (inQuotes && line[i + 1] === '"') {
+          current += '"';
+          i++;
+        } else {
+          inQuotes = !inQuotes;
+        }
+      } else if (char === ',' && !inQuotes) {
+        result.push(current.trim());
+        current = '';
+      } else {
+        current += char;
+      }
+    }
+    result.push(current.trim());
+    return result;
+  }
+
+  function parseCSVWithMapping(content: string, mapping: Record<string, keyof SubscriptionInput | ''>): SubscriptionInput[] {
+    const lines = content.split(/\r?\n/).filter((l) => l.trim());
+    if (lines.length < 2) return [];
+    const rawHeaders = parseLine(lines[0]);
+    const headerIndex: Record<string, number> = {};
+    rawHeaders.forEach((h, i) => (headerIndex[h.toLowerCase()] = i));
+
+    const result: SubscriptionInput[] = [];
+
+    for (let i = 1; i < lines.length; i++) {
+      const values = parseLine(lines[i]);
+      if (values.every((v) => !v)) continue;
+
+      const row: Partial<SubscriptionInput> = {};
+
+      for (const raw of Object.keys(mapping)) {
+        const target = mapping[raw];
+        if (!target) continue;
+        const idx = headerIndex[raw.toLowerCase()];
+        const rawValue = typeof idx === 'number' && values[idx] ? values[idx] : '';
+        (row as any)[target] = rawValue;
+      }
+
+      // ensure required defaults
+      if (!row.name && values[0]) row.name = values[0];
+
+      // Cast numeric-ish fields
+      if (row.price !== undefined) row.price = Number(row.price as any) || 0;
+
+      if (row.nextBillingDate && typeof row.nextBillingDate !== 'string') {
+        row.nextBillingDate = String(row.nextBillingDate);
+      }
+
+      result.push(row as SubscriptionInput);
+    }
+
+    return result;
+  }
+
+  const openMappingModal = () => {
+    if (detectedHeaders.length === 0) {
+      Alert.alert('No headers detected', 'Please paste a CSV with headers first');
+      return;
+    }
+
+    const initial: Record<string, keyof SubscriptionInput | ''> = {};
+    detectedHeaders.forEach((h) => {
+      initial[h] = columnMapping[h] ?? '';
+    });
+    setColumnMapping(initial);
+    setShowMappingModal(true);
+  };
+
+  const cycleMappingFor = (header: string) => {
+    const options = ['','name','description','category','price','currency','billingCycle','nextBillingDate','isActive','notificationsEnabled','isCryptoEnabled','cryptoToken','cryptoAmount'] as (keyof SubscriptionInput | '')[];
+    const current = columnMapping[header] ?? '';
+    const idx = options.indexOf(current);
+    const next = options[(idx + 1) % options.length];
+    setColumnMapping((m) => ({ ...m, [header]: next }));
+  };
+
   const executeImport = async (parsedData: SubscriptionInput[]) => {
     setIsProcessing(true);
-
     try {
       const result = processImport({ subscriptions: parsedData, mode: importMode }, subscriptions);
 
       setImportResult(result);
 
-      // Apply the import
+      // Apply the import with progress and rollback support
       if (result.imported > 0 || result.updated > 0) {
-        for (const sub of parsedData) {
-          const existing = subscriptions.find(
-            (s) => s.name.toLowerCase() === sub.name.toLowerCase()
-          );
-
-          if (existing) {
-            // Update existing
-            await updateSubscription(existing.id, {
-              name: sub.name,
-              description: sub.description,
-              category: sub.category as any,
-              price: sub.price,
-              currency: sub.currency,
-              billingCycle: sub.billingCycle as any,
-              nextBillingDate: new Date(sub.nextBillingDate),
-              isActive: sub.isActive ?? true,
-              notificationsEnabled: sub.notificationsEnabled ?? true,
-              isCryptoEnabled: sub.isCryptoEnabled ?? false,
-              cryptoToken: sub.cryptoToken,
-              cryptoAmount: sub.cryptoAmount,
-            });
-          } else {
-            // Add new
-            await addSubscription({
-              name: sub.name,
-              description: sub.description,
-              category: sub.category as any,
-              price: sub.price,
-              currency: sub.currency,
-              billingCycle: sub.billingCycle as any,
-              nextBillingDate: new Date(sub.nextBillingDate),
-              notificationsEnabled: sub.notificationsEnabled ?? true,
-              isCryptoEnabled: sub.isCryptoEnabled ?? false,
-              cryptoToken: sub.cryptoToken,
-              cryptoAmount: sub.cryptoAmount,
-            });
+        const snapshot = useSubscriptionStore.getState().subscriptions.map((s) => ({ ...s }));
+        let processed = 0;
+        try {
+          for (const sub of parsedData) {
+            setProgress({ current: processed + 1, total: parsedData.length, message: `Processing ${sub.name}` });
+            const existing = useSubscriptionStore.getState().subscriptions.find(
+              (s) => s.name.toLowerCase() === sub.name.toLowerCase()
+            );
+
+            if (existing) {
+              await updateSubscription(existing.id, {
+                name: sub.name,
+                description: sub.description,
+                category: sub.category as any,
+                price: sub.price,
+                currency: sub.currency,
+                billingCycle: sub.billingCycle as any,
+                nextBillingDate: new Date(sub.nextBillingDate),
+                isActive: sub.isActive ?? true,
+                notificationsEnabled: sub.notificationsEnabled ?? true,
+                isCryptoEnabled: sub.isCryptoEnabled ?? false,
+                cryptoToken: sub.cryptoToken,
+                cryptoAmount: sub.cryptoAmount,
+              });
+            } else {
+              await addSubscription({
+                name: sub.name,
+                description: sub.description,
+                category: sub.category as any,
+                price: sub.price,
+                currency: sub.currency,
+                billingCycle: sub.billingCycle as any,
+                nextBillingDate: new Date(sub.nextBillingDate),
+                notificationsEnabled: sub.notificationsEnabled ?? true,
+                isCryptoEnabled: sub.isCryptoEnabled ?? false,
+                cryptoToken: sub.cryptoToken,
+                cryptoAmount: sub.cryptoAmount,
+              });
+            }
+            processed += 1;
+            setProgress({ current: processed, total: parsedData.length, message: `Processed ${processed}/${parsedData.length}` });
           }
+        } catch (applyErr) {
+          // Rollback to snapshot on failure
+          useSubscriptionStore.setState({ subscriptions: snapshot });
+          useSubscriptionStore.getState().calculateStats();
+          throw applyErr;
         }
       }
 
@@ -171,6 +284,7 @@ const ImportScreen: React.FC = () => {
       Alert.alert('Error', error instanceof Error ? error.message : 'Failed to complete import');
     } finally {
       setIsProcessing(false);
+      setProgress(null);
     }
   };
 
@@ -373,9 +487,14 @@ const ImportScreen: React.FC = () => {
         <Card style={styles.inputCard}>
           <View style={styles.inputHeader}>
             <Text style={styles.sectionTitle}>Import Data</Text>
-            <TouchableOpacity onPress={() => setShowTemplateModal(true)}>
-              <Text style={styles.templateLink}>Load Template</Text>
-            </TouchableOpacity>
+            <View style={{ flexDirection: 'row', gap: 12 }}>
+              <TouchableOpacity onPress={() => setShowTemplateModal(true)}>
+                <Text style={styles.templateLink}>Load Template</Text>
+              </TouchableOpacity>
+              <TouchableOpacity onPress={() => openMappingModal()}>
+                <Text style={styles.templateLink}>Map Columns</Text>
+              </TouchableOpacity>
+            </View>
           </View>
           <TextInput
             style={styles.textArea}
@@ -407,6 +526,14 @@ const ImportScreen: React.FC = () => {
           />
         </View>
 
+        {progress && (
+          <Card style={[styles.resultCard, { marginHorizontal: spacing.lg }]}> 
+            <Text style={styles.resultTitle}>Import Progress</Text>
+            <Text style={styles.resultLabel}>{progress.message}</Text>
+            <Text style={styles.resultValue}>{progress.current} / {progress.total}</Text>
+          </Card>
+        )}
+
         <TouchableOpacity style={styles.historyLink} onPress={loadHistory}>
           <Text style={styles.historyLinkText}>View Import History</Text>
         </TouchableOpacity>
@@ -414,6 +541,42 @@ const ImportScreen: React.FC = () => {
 
       {renderHistoryModal()}
       {renderTemplateModal()}
+      {/* Column mapping modal */}
+      <Modal
+        visible={showMappingModal}
+        animationType="slide"
+        presentationStyle="pageSheet"
+        onRequestClose={() => setShowMappingModal(false)}>
+        <SafeAreaView style={styles.modalContainer}>
+          <View style={styles.modalHeader}>
+            <Text style={styles.modalTitle}>Map CSV Columns</Text>
+            <TouchableOpacity onPress={() => setShowMappingModal(false)}>
+              <Text style={styles.closeButton}>Close</Text>
+            </TouchableOpacity>
+          </View>
+          <View style={{ padding: spacing.lg }}>
+            <Text style={styles.sectionTitle}>Detected Headers</Text>
+            <FlatList
+              data={detectedHeaders}
+              keyExtractor={(item) => item}
+              renderItem={({ item }) => (
+                <TouchableOpacity
+                  style={{ padding: spacing.md, borderBottomWidth: 1, borderColor: colors.border }}
+                  onPress={() => cycleMappingFor(item)}>
+                  <Text style={typography.body}>{item}</Text>
+                  <Text style={[typography.caption, { color: colors.textSecondary }]}>Mapping: {String(columnMapping[item] || '(none)')}</Text>
+                </TouchableOpacity>
+              )}
+            />
+            <View style={{ marginTop: spacing.md }}>
+              <Button title="Apply Mapping" onPress={() => setShowMappingModal(false)} />
+            </View>
+            <View style={{ marginTop: spacing.sm }}>
+              <Text style={typography.caption}>Tap a header to cycle through target fields.</Text>
+            </View>
+          </View>
+        </SafeAreaView>
+      </Modal>
     </SafeAreaView>
   );
 };
diff --git a/src/utils/__tests__/importExport.test.ts b/src/utils/__tests__/importExport.test.ts
index 437e5c8..cbff4f4 100644
--- a/src/utils/__tests__/importExport.test.ts
+++ b/src/utils/__tests__/importExport.test.ts
@@ -1,3 +1,60 @@
+import {
+  parseCSV,
+  detectFormat,
+  parseJSON,
+  validateImport,
+  processImport,
+  ImportData,
+  ImportMode,
+} from '../importExport';
+
+describe('importExport utilities', () => {
+  test('detectFormat identifies csv and json', () => {
+    const csv = 'name,price\nNetflix,9.99';
+    const json = JSON.stringify([{ id: '1', name: 'Netflix' }]);
+    expect(detectFormat(csv)).toBe('csv');
+    expect(detectFormat(json)).toBe('json');
+  });
+
+  test('parseCSV parses CSV rows', () => {
+    const csv = 'name,price,currency\nTest Service,12.5,USD\nOther,0,EUR';
+    const parsed = parseCSV(csv);
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].name).toBe('Test Service');
+    expect(parsed[0].price).toBeCloseTo(12.5);
+  });
+
+  test('validateImport finds missing required fields', () => {
+    const data: ImportData = {
+      subscriptions: [
+        { name: '', category: 'other', price: 10, currency: 'USD', billingCycle: 'monthly', nextBillingDate: '2026-01-01' },
+        { name: 'Valid', category: 'other', price: -5, currency: 'USD', billingCycle: 'monthly', nextBillingDate: 'invalid-date' },
+      ],
+      mode: 'create' as ImportMode,
+    };
+
+    const validation = validateImport(data);
+    expect(validation.isValid).toBe(false);
+    expect(validation.errors.length).toBeGreaterThan(0);
+  });
+
+  test('processImport creates and updates subscriptions correctly', () => {
+    const existing = [
+      { id: 'a', name: 'Existing', description: '', category: 'other', price: 5, currency: 'USD', billingCycle: 'monthly', nextBillingDate: '2026-05-01', isActive: true, notificationsEnabled: true, isCryptoEnabled: false, createdAt: new Date(), updatedAt: new Date() },
+    ];
+
+    const data: ImportData = {
+      subscriptions: [
+        { id: 'a', name: 'Existing', category: 'other', price: 7, currency: 'USD', billingCycle: 'monthly', nextBillingDate: '2026-06-01' },
+        { name: 'NewSub', category: 'other', price: 3.5, currency: 'USD', billingCycle: 'monthly', nextBillingDate: '2026-07-01' },
+      ],
+      mode: 'upsert' as ImportMode,
+    };
+
+    const result = processImport(data, existing as any);
+    expect(result.imported + result.updated).toBeGreaterThanOrEqual(2);
+  });
+});
 /**
  * Import/Export Tests
  */

From 74c9415b5f035e1ef38166aba1c141ce4896344d Mon Sep 17 00:00:00 2001
From: dee-john <johnezekiel376@gmail.com>
Date: Sun, 31 May 2026 08:15:40 +0100
Subject: [PATCH 2/2] chore: finalize import system implementation - issue #391

- CSV import with advanced column mapping
- Stripe and Chargebee API helpers
- Full validation with error/warning reporting
- Duplicate detection with merge strategies
- Progress tracking and rollback on failure
- Import history tracking

Closes #391
---
 src/screens/ImportScreen.tsx             | 111 +++++----
 src/store/subscriptionStore.ts           |   6 +-
 src/types/subscription.ts                |   4 +
 src/utils/__tests__/importExport.test.ts |  64 +++++
 src/utils/importExport.ts                | 288 +++++++++++++++--------
 5 files changed, 329 insertions(+), 144 deletions(-)

diff --git a/src/screens/ImportScreen.tsx b/src/screens/ImportScreen.tsx
index b349340..cf7d1c2 100644
--- a/src/screens/ImportScreen.tsx
+++ b/src/screens/ImportScreen.tsx
@@ -35,7 +35,7 @@ import {
 import { useSubscriptionStore } from '../store';
 
 const ImportScreen: React.FC = () => {
-  const { subscriptions, addSubscription, updateSubscription } = useSubscriptionStore();
+  const { subscriptions, addSubscription, updateSubscription, deleteSubscription } = useSubscriptionStore();
   const navigation = useNavigation<any>();
 
   const [importMode, setImportMode] = useState<ImportMode>('upsert');
@@ -173,15 +173,25 @@ const ImportScreen: React.FC = () => {
         if (!target) continue;
         const idx = headerIndex[raw.toLowerCase()];
         const rawValue = typeof idx === 'number' && values[idx] ? values[idx] : '';
-        (row as any)[target] = rawValue;
+        let value: unknown = rawValue;
+
+        if (target === 'price' || target === 'cryptoAmount') {
+          value = Number(rawValue) || 0;
+        } else if (
+          target === 'isActive' ||
+          target === 'notificationsEnabled' ||
+          target === 'isCryptoEnabled'
+        ) {
+          const normalized = rawValue.toString().trim().toLowerCase();
+          value = normalized === 'true' || normalized === '1' || normalized === 'yes';
+        }
+
+        (row as any)[target] = value;
       }
 
       // ensure required defaults
       if (!row.name && values[0]) row.name = values[0];
 
-      // Cast numeric-ish fields
-      if (row.price !== undefined) row.price = Number(row.price as any) || 0;
-
       if (row.nextBillingDate && typeof row.nextBillingDate !== 'string') {
         row.nextBillingDate = String(row.nextBillingDate);
       }
@@ -207,7 +217,7 @@ const ImportScreen: React.FC = () => {
   };
 
   const cycleMappingFor = (header: string) => {
-    const options = ['','name','description','category','price','currency','billingCycle','nextBillingDate','isActive','notificationsEnabled','isCryptoEnabled','cryptoToken','cryptoAmount'] as (keyof SubscriptionInput | '')[];
+    const options = ['','name','description','category','price','currency','billingCycle','nextBillingDate','isActive','notificationsEnabled','isCryptoEnabled','cryptoToken','cryptoAmount','externalId','externalSource'] as (keyof SubscriptionInput | '')[];
     const current = columnMapping[header] ?? '';
     const idx = options.indexOf(current);
     const next = options[(idx + 1) % options.length];
@@ -218,52 +228,71 @@ const ImportScreen: React.FC = () => {
     setIsProcessing(true);
     try {
       const result = processImport({ subscriptions: parsedData, mode: importMode }, subscriptions);
-
       setImportResult(result);
 
+      const actions = result.actions ?? [];
+
       // Apply the import with progress and rollback support
-      if (result.imported > 0 || result.updated > 0) {
+      if (actions.length > 0) {
         const snapshot = useSubscriptionStore.getState().subscriptions.map((s) => ({ ...s }));
         let processed = 0;
+        const appliedIds = new Set<string>();
+
         try {
-          for (const sub of parsedData) {
-            setProgress({ current: processed + 1, total: parsedData.length, message: `Processing ${sub.name}` });
-            const existing = useSubscriptionStore.getState().subscriptions.find(
-              (s) => s.name.toLowerCase() === sub.name.toLowerCase()
-            );
-
-            if (existing) {
-              await updateSubscription(existing.id, {
-                name: sub.name,
-                description: sub.description,
-                category: sub.category as any,
-                price: sub.price,
-                currency: sub.currency,
-                billingCycle: sub.billingCycle as any,
-                nextBillingDate: new Date(sub.nextBillingDate),
-                isActive: sub.isActive ?? true,
-                notificationsEnabled: sub.notificationsEnabled ?? true,
-                isCryptoEnabled: sub.isCryptoEnabled ?? false,
-                cryptoToken: sub.cryptoToken,
-                cryptoAmount: sub.cryptoAmount,
+          for (const action of actions) {
+            const subscription = action.subscription;
+            if (!subscription) continue;
+
+            setProgress({ current: processed + 1, total: actions.length, message: `Processing ${subscription.name}` });
+
+            if (action.type === 'update' && action.existingId) {
+              await updateSubscription(action.existingId, {
+                name: subscription.name,
+                description: subscription.description,
+                category: subscription.category as any,
+                price: subscription.price,
+                currency: subscription.currency,
+                billingCycle: subscription.billingCycle as any,
+                nextBillingDate: new Date(subscription.nextBillingDate),
+                isActive: subscription.isActive,
+                notificationsEnabled: subscription.notificationsEnabled,
+                isCryptoEnabled: subscription.isCryptoEnabled,
+                cryptoToken: subscription.cryptoToken,
+                cryptoAmount: subscription.cryptoAmount,
+                externalId: subscription.externalId,
+                externalSource: subscription.externalSource,
               });
-            } else {
+              appliedIds.add(action.existingId);
+            } else if (action.type === 'create') {
               await addSubscription({
-                name: sub.name,
-                description: sub.description,
-                category: sub.category as any,
-                price: sub.price,
-                currency: sub.currency,
-                billingCycle: sub.billingCycle as any,
-                nextBillingDate: new Date(sub.nextBillingDate),
-                notificationsEnabled: sub.notificationsEnabled ?? true,
-                isCryptoEnabled: sub.isCryptoEnabled ?? false,
-                cryptoToken: sub.cryptoToken,
-                cryptoAmount: sub.cryptoAmount,
+                id: subscription.id,
+                name: subscription.name,
+                description: subscription.description,
+                category: subscription.category as any,
+                price: subscription.price,
+                currency: subscription.currency,
+                billingCycle: subscription.billingCycle as any,
+                nextBillingDate: new Date(subscription.nextBillingDate),
+                notificationsEnabled: subscription.notificationsEnabled ?? true,
+                isCryptoEnabled: subscription.isCryptoEnabled ?? false,
+                cryptoToken: subscription.cryptoToken,
+                cryptoAmount: subscription.cryptoAmount,
+                externalId: subscription.externalId,
+                externalSource: subscription.externalSource,
               });
+              appliedIds.add(subscription.id);
             }
+
             processed += 1;
-            setProgress({ current: processed, total: parsedData.length, message: `Processed ${processed}/${parsedData.length}` });
+            setProgress({ current: processed, total: actions.length, message: `Processed ${processed}/${actions.length}` });
+          }
+
+          if (importMode === 'replace') {
+            const currentSubscriptions = useSubscriptionStore.getState().subscriptions;
+            const toDelete = currentSubscriptions.filter((sub) => !appliedIds.has(sub.id));
+            for (const sub of toDelete) {
+              await deleteSubscription(sub.id);
+            }
           }
         } catch (applyErr) {
           // Rollback to snapshot on failure
diff --git a/src/store/subscriptionStore.ts b/src/store/subscriptionStore.ts
index cd6bb4a..c06cf83 100644
--- a/src/store/subscriptionStore.ts
+++ b/src/store/subscriptionStore.ts
@@ -164,7 +164,7 @@ interface SubscriptionState {
   creditMemos: Record<string, CreditMemo>;
 
   // Actions
-  addSubscription: (data: SubscriptionFormData) => Promise<void>;
+  addSubscription: (data: SubscriptionFormData & { id?: string; externalId?: string; externalSource?: string }) => Promise<void>;
   updateSubscription: (id: string, data: Partial<Subscription>) => Promise<void>;
   deleteSubscription: (id: string) => Promise<void>;
   toggleSubscriptionStatus: (id: string) => Promise<void>;
@@ -273,11 +273,11 @@ export const useSubscriptionStore = create<SubscriptionState>()(
       isLoading: true,
       error: null,
 
-      addSubscription: async (data: SubscriptionFormData) => {
+      addSubscription: async (data: SubscriptionFormData & { id?: string; externalId?: string; externalSource?: string }) => {
         set({ isLoading: true, error: null });
         try {
           const newSubscription: Subscription = {
-            id: generateUniqueId(),
+            id: data.id ?? generateUniqueId(),
             ...data,
             isActive: true,
             notificationsEnabled: data.notificationsEnabled !== false,
diff --git a/src/types/subscription.ts b/src/types/subscription.ts
index d7ac5a9..a443171 100644
--- a/src/types/subscription.ts
+++ b/src/types/subscription.ts
@@ -14,6 +14,8 @@ export interface Subscription {
   cryptoStreamId?: string;
   cryptoToken?: string;
   cryptoAmount?: number;
+  externalId?: string;
+  externalSource?: string;
   gasBudget?: number;
   totalGasSpent?: number;
   chargeCount?: number;
@@ -80,6 +82,8 @@ export interface SubscriptionFormData {
   isCryptoEnabled: boolean;
   cryptoToken?: string;
   cryptoAmount?: number;
+  externalId?: string;
+  externalSource?: string;
 }
 
 export interface SubscriptionStats {
diff --git a/src/utils/__tests__/importExport.test.ts b/src/utils/__tests__/importExport.test.ts
index cbff4f4..1e554bb 100644
--- a/src/utils/__tests__/importExport.test.ts
+++ b/src/utils/__tests__/importExport.test.ts
@@ -410,6 +410,70 @@ Spotify,Music streaming,streaming,9.99,USD,monthly,2026-05-15`;
       const result = processImport(data, existing);
       expect(result.imported).toBe(0);
       expect(result.failed).toBe(1);
+      expect(result.actions).toHaveLength(0);
+    });
+
+    it('should preserve externalId during import', () => {
+      const data = {
+        subscriptions: [
+          {
+            name: 'Stripe Plan',
+            externalId: 'stripe_123',
+            externalSource: 'stripe',
+            category: 'streaming',
+            price: 15.99,
+            currency: 'USD',
+            billingCycle: 'monthly',
+            nextBillingDate: '2026-05-01',
+          },
+        ],
+        mode: 'create' as ImportMode,
+      };
+
+      const result = processImport(data, []);
+      expect(result.success).toBe(true);
+      expect(result.imported).toBe(1);
+      expect(result.actions?.[0].subscription?.externalId).toBe('stripe_123');
+      expect(result.actions?.[0].subscription?.externalSource).toBe('stripe');
+    });
+
+    it('should replace existing subscriptions when replace mode is selected', () => {
+      const existing: Subscription[] = [
+        {
+          id: '1',
+          name: 'Old Service',
+          category: SubscriptionCategory.OTHER,
+          price: 5,
+          currency: 'USD',
+          billingCycle: BillingCycle.MONTHLY,
+          nextBillingDate: new Date('2026-05-01'),
+          isActive: true,
+          notificationsEnabled: true,
+          isCryptoEnabled: false,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      ];
+
+      const data = {
+        subscriptions: [
+          {
+            name: 'New Service',
+            category: 'software',
+            price: 20,
+            currency: 'USD',
+            billingCycle: 'monthly',
+            nextBillingDate: '2026-06-01',
+          },
+        ],
+        mode: 'replace' as ImportMode,
+      };
+
+      const result = processImport(data, existing);
+      expect(result.success).toBe(true);
+      expect(result.imported).toBe(1);
+      expect(result.updated).toBe(0);
+      expect(result.actions?.[0].type).toBe('create');
     });
   });
 
diff --git a/src/utils/importExport.ts b/src/utils/importExport.ts
index f965c9d..1509e75 100644
--- a/src/utils/importExport.ts
+++ b/src/utils/importExport.ts
@@ -17,6 +17,8 @@ export interface ImportData {
 
 export interface SubscriptionInput {
   id?: string;
+  externalId?: string;
+  externalSource?: string;
   name: string;
   description?: string;
   category: string;
@@ -33,6 +35,14 @@ export interface SubscriptionInput {
 
 export type ImportMode = 'create' | 'upsert' | 'replace';
 
+export interface ImportAction {
+  type: 'create' | 'update' | 'skip';
+  row: number;
+  subscription?: Subscription;
+  existingId?: string;
+  message?: string;
+}
+
 export interface ImportResult {
   success: boolean;
   imported: number;
@@ -40,6 +50,7 @@ export interface ImportResult {
   failed: number;
   errors: ImportError[];
   warnings: ImportWarning[];
+  actions?: ImportAction[];
 }
 
 export interface ImportError {
@@ -116,6 +127,7 @@ export const CSV_COLUMN_MAPPING: ColumnMapping[] = [
   },
   { csvColumn: 'cryptoToken', fieldName: 'cryptoToken', required: false },
   { csvColumn: 'cryptoAmount', fieldName: 'cryptoAmount', required: false, transform: parseFloat },
+  { csvColumn: 'externalId', fieldName: 'externalId', required: false },
 ];
 
 export const VALID_CATEGORIES = Object.values(SubscriptionCategory);
@@ -180,28 +192,185 @@ function normalizeBillingCycle(value: string): BillingCycle {
 }
 
 function parseDate(value: string): Date {
-  const parsed = new Date(value);
+  const normalized = value?.toString().trim();
+  if (!normalized) {
+    return new Date();
+  }
+
+  const numeric = Number(normalized);
+  if (!Number.isNaN(numeric)) {
+    return normalized.length >= 13 ? new Date(numeric) : new Date(numeric * 1000);
+  }
+
+  const parsed = new Date(normalized);
   if (!Number.isNaN(parsed.getTime())) {
     return parsed;
   }
-  // Try common formats
+
+  const dateOnlyMatch = normalized.match(/^\d{4}-\d{2}-\d{2}$/);
+  if (dateOnlyMatch) {
+    return new Date(`${normalized}T00:00:00Z`);
+  }
+
   const formats = [
-    /^(\d{4})-(\d{2})-(\d{2})$/, // YYYY-MM-DD
-    /^(\d{2})\/(\d{2})\/(\d{4})$/, // MM/DD/YYYY
-    /^(\d{2})-(\d{2})-(\d{4})$/, // DD-MM-YYYY
+    /^(\d{2})\/(\d{2})\/(\d{4})$/,
+    /^(\d{2})-(\d{2})-(\d{4})$/,
   ];
 
   for (const format of formats) {
-    const match = value.match(format);
+    const match = normalized.match(format);
     if (match) {
-      const date = new Date(value);
+      const date = new Date(normalized);
       if (!Number.isNaN(date.getTime())) {
         return date;
       }
     }
   }
 
-  return new Date(); // Default to current date
+  return new Date();
+}
+
+function parseSubscriptionField(field: keyof SubscriptionInput, rawValue?: string): unknown {
+  if (rawValue === undefined || rawValue === null) {
+    return undefined;
+  }
+
+  const trimmed = rawValue.toString().trim();
+  if (trimmed === '') {
+    return undefined;
+  }
+
+  switch (field) {
+    case 'price':
+    case 'cryptoAmount':
+      return Number(trimmed);
+    case 'isActive':
+    case 'notificationsEnabled':
+    case 'isCryptoEnabled':
+      return parseBoolean(trimmed);
+    default:
+      return trimmed;
+  }
+}
+
+function buildSubscriptionFromInput(input: SubscriptionInput, existing?: Subscription): Subscription {
+  const now = new Date();
+  const id = existing?.id ?? input.id ?? generateUniqueId();
+
+  return {
+    id,
+    name: input.name,
+    description: input.description,
+    category: normalizeCategory(input.category),
+    price: input.price,
+    currency: input.currency?.toUpperCase() || 'USD',
+    billingCycle: normalizeBillingCycle(input.billingCycle),
+    nextBillingDate: parseDate(input.nextBillingDate),
+    isActive: input.isActive ?? existing?.isActive ?? true,
+    notificationsEnabled: input.notificationsEnabled ?? existing?.notificationsEnabled ?? true,
+    isCryptoEnabled: input.isCryptoEnabled ?? existing?.isCryptoEnabled ?? false,
+    cryptoToken: input.cryptoToken ?? existing?.cryptoToken,
+    cryptoAmount: input.cryptoAmount ?? existing?.cryptoAmount,
+    externalId: input.externalId ?? existing?.externalId,
+    externalSource: input.externalSource ?? existing?.externalSource,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+  };
+}
+
+function buildImportActions(data: ImportData, existingSubscriptions: Subscription[]): {
+  actions: ImportAction[];
+  errors: ImportError[];
+  warnings: ImportWarning[];
+} {
+  const validation = validateImport(data);
+  const existingByName = new Map<string, Subscription>();
+  const existingById = new Map<string, Subscription>();
+  const existingByExternalId = new Map<string, Subscription>();
+
+  existingSubscriptions.forEach((sub) => {
+    existingByName.set(sub.name.toLowerCase(), sub);
+    if (sub.id) existingById.set(sub.id, sub);
+    if (sub.externalId) existingByExternalId.set(sub.externalId, sub);
+  });
+
+  const seenNames = new Set<string>();
+  const seenIds = new Set<string>();
+  const seenExternalIds = new Set<string>();
+  const actions: ImportAction[] = [];
+  const errors = [...validation.errors];
+  const warnings = [...validation.warnings];
+
+  validation.validRows.forEach((input, index) => {
+    const rowNum = index + 1;
+    const normalizedName = input.name.toLowerCase().trim();
+
+    if (seenNames.has(normalizedName)) {
+      errors.push({
+        row: rowNum,
+        field: 'name',
+        message: 'Duplicate subscription name found in import file',
+        value: input.name,
+      });
+      return;
+    }
+
+    if (input.id && seenIds.has(input.id)) {
+      errors.push({
+        row: rowNum,
+        field: 'id',
+        message: 'Duplicate subscription id found in import file',
+        value: input.id,
+      });
+      return;
+    }
+
+    if (input.externalId && seenExternalIds.has(input.externalId)) {
+      errors.push({
+        row: rowNum,
+        field: 'externalId',
+        message: 'Duplicate external id found in import file',
+        value: input.externalId,
+      });
+      return;
+    }
+
+    seenNames.add(normalizedName);
+    if (input.id) seenIds.add(input.id);
+    if (input.externalId) seenExternalIds.add(input.externalId);
+
+    const existingByIdMatch = input.id ? existingById.get(input.id) : undefined;
+    const existingByExternalIdMatch = input.externalId
+      ? existingByExternalId.get(input.externalId)
+      : undefined;
+    const existingByNameMatch = existingByName.get(normalizedName);
+    const existing = existingByIdMatch || existingByExternalIdMatch || existingByNameMatch;
+
+    if (data.mode === 'create') {
+      if (existing) {
+        errors.push({
+          row: rowNum,
+          field: existingByIdMatch ? 'id' : existingByExternalIdMatch ? 'externalId' : 'name',
+          message: 'Duplicate subscription found; create mode skips existing items',
+          value: existingByIdMatch ? input.id : input.externalId || input.name,
+        });
+        return;
+      }
+
+      actions.push({ type: 'create', row: rowNum, subscription: buildSubscriptionFromInput(input) });
+      return;
+    }
+
+    const subscription = buildSubscriptionFromInput(input, existing);
+    if (existing) {
+      actions.push({ type: 'update', row: rowNum, existingId: existing.id, subscription });
+      return;
+    }
+
+    actions.push({ type: 'create', row: rowNum, subscription });
+  });
+
+  return { actions, errors, warnings };
 }
 
 // ============================================
@@ -241,7 +410,9 @@ export function parseCSV(csvContent: string): SubscriptionInput[] {
       const columnIndex = headerMap.get(mapping.csvColumn.toLowerCase());
       if (columnIndex !== undefined && values[columnIndex]) {
         const rawValue = values[columnIndex];
-        const value = mapping.transform ? String(mapping.transform(rawValue)) : rawValue;
+        const value = mapping.transform
+          ? mapping.transform(rawValue)
+          : parseSubscriptionField(mapping.fieldName, rawValue);
 
         (subscription as Record<string, unknown>)[mapping.fieldName] = value;
       }
@@ -357,6 +528,8 @@ export function parseJSON(jsonContent: string): SubscriptionInput[] {
 
   return subscriptions.map((sub) => ({
     id: sub.id,
+    externalId: (sub as any).externalId,
+    externalSource: (sub as any).externalSource,
     name: sub.name,
     description: sub.description,
     category: typeof sub.category === 'string' ? sub.category : SubscriptionCategory.OTHER,
@@ -515,109 +688,24 @@ export function processImport(
   data: ImportData,
   existingSubscriptions: Subscription[]
 ): ImportResult {
-  const validation = validateImport(data);
-
-  if (validation.validRows.length === 0 && validation.errors.length > 0) {
-    return {
-      success: false,
-      imported: 0,
-      updated: 0,
-      failed: data.subscriptions.length,
-      errors: validation.errors,
-      warnings: validation.warnings,
-    };
-  }
+  const { actions, errors, warnings } = buildImportActions(data, existingSubscriptions);
 
   let imported = 0;
   let updatedCount = 0;
-  const errors: ImportError[] = [...validation.errors];
-  const warnings: ImportWarning[] = [...validation.warnings];
-
-  // Create lookup for existing subscriptions
-  const existingByName = new Map<string, Subscription>();
-  const existingById = new Map<string, Subscription>();
-
-  existingSubscriptions.forEach((sub) => {
-    existingByName.set(sub.name.toLowerCase(), sub);
-    if (sub.id) {
-      existingById.set(sub.id, sub);
-    }
-  });
 
-  const processedSubscriptions: Subscription[] = [];
-
-  validation.validRows.forEach((input, index) => {
-    const rowNum = index + 1;
-    const now = new Date();
-
-    try {
-      // Check for duplicates
-      const existingByNameMatch = existingByName.get(input.name.toLowerCase());
-      const existingByIdMatch = input.id ? existingById.get(input.id) : null;
-      const isUpdate = (existingByNameMatch || existingByIdMatch) && data.mode === 'upsert';
-      const isReplace = data.mode === 'replace';
-
-      if (isUpdate || isReplace) {
-        // Update existing
-        const existing = existingByIdMatch || existingByNameMatch;
-        if (existing) {
-          const merged: Subscription = {
-            ...existing,
-            name: input.name,
-            description: input.description,
-            category: normalizeCategory(input.category),
-            price: input.price,
-            currency: input.currency?.toUpperCase() || 'USD',
-            billingCycle: normalizeBillingCycle(input.billingCycle),
-            nextBillingDate: parseDate(input.nextBillingDate),
-            isActive: input.isActive ?? existing.isActive,
-            notificationsEnabled: input.notificationsEnabled ?? existing.notificationsEnabled,
-            isCryptoEnabled: input.isCryptoEnabled ?? existing.isCryptoEnabled,
-            cryptoToken: input.cryptoToken ?? existing.cryptoToken,
-            cryptoAmount: input.cryptoAmount ?? existing.cryptoAmount,
-            updatedAt: now,
-          };
-          processedSubscriptions.push(merged);
-          updatedCount++;
-        }
-      } else {
-        // Create new
-        const newSubscription: Subscription = {
-          id: input.id || generateUniqueId(),
-          name: input.name,
-          description: input.description,
-          category: normalizeCategory(input.category),
-          price: input.price,
-          currency: input.currency?.toUpperCase() || 'USD',
-          billingCycle: normalizeBillingCycle(input.billingCycle),
-          nextBillingDate: parseDate(input.nextBillingDate),
-          isActive: input.isActive ?? true,
-          notificationsEnabled: input.notificationsEnabled ?? true,
-          isCryptoEnabled: input.isCryptoEnabled ?? false,
-          cryptoToken: input.cryptoToken,
-          cryptoAmount: input.cryptoAmount,
-          createdAt: now,
-          updatedAt: now,
-        };
-        processedSubscriptions.push(newSubscription);
-        imported++;
-      }
-    } catch (err) {
-      errors.push({
-        row: rowNum,
-        field: 'general',
-        message: err instanceof Error ? err.message : 'Unknown error',
-      });
-    }
+  actions.forEach((action) => {
+    if (action.type === 'create') imported += 1;
+    if (action.type === 'update') updatedCount += 1;
   });
 
   return {
     success: errors.length === 0,
     imported,
     updated: updatedCount,
-    failed: data.subscriptions.length - imported - updatedCount,
+    failed: errors.length,
     errors,
     warnings,
+    actions,
   };
 }