Source Installation Management

Monitor integration health, troubleshoot issues, and automate customer success workflows with the Source Installation API.

Source installations represent the individual connections between your data sources and customer subscriptions. While most installation management happens through the UI, the API lets you monitor integration health, diagnose issues, and build automation workflows.

Core concepts

Installation vs. source

• Source: The template configuration (what data to collect, how to process it)
• Installation: The live connection between a source and a specific customer subscription

Installation lifecycle

1. Active: Integration working properly, data flowing
2. Disconnected: Customer manually disconnected or credentials expired
3. Error: Technical failure, invalid credentials, or API issues

Provider types

• Ampersand: Most common, handles OAuth flows and webhook management
• OAuth: Direct OAuth integrations (Coming Soon)
• API Key: Simple credential-based connections (Coming Soon)

Health monitoring

Monitor your customers’ integration health programmatically to catch issues before they impact revenue tracking.

Check single customer status

Monitor a specific customer’s integration:

const response = await fetch(
  `https://api.paygentic.io/v0/sources/${sourceId}/installations?subscriptionId=${customerId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.PAYGENTIC_API_KEY}`
    }
  }
);

const { data: installations } = await response.json();
const installation = installations[0];

if (!installation) {
  console.log('❌ Customer has not connected their integration');
} else if (installation.status !== 'active') {
  console.log('⚠️ Integration issue:', installation.errorMessage);
  console.log('Last sync:', installation.lastSyncAt);
} else {
  console.log('✅ Integration healthy');
}

Find problematic integrations

Identify customers whose integrations need attention:

// Get all disconnected integrations
const disconnected = await fetch(
  `https://api.paygentic.io/v0/sources/${sourceId}/installations?status=disconnected`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

// Get integrations with errors
const errors = await fetch(
  `https://api.paygentic.io/v0/sources/${sourceId}/installations?status=error`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

console.log(`${disconnected.data.length} customers disconnected`);
console.log(`${errors.data.length} customers have errors`);

Build health dashboard

Get an overview of all customer integrations:

const response = await fetch(
  `https://api.paygentic.io/v0/sources/${sourceId}/installations?limit=100`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const installations = await response.json();

const healthStats = {
  total: installations.data.length,
  active: installations.data.filter(i => i.status === 'active').length,
  disconnected: installations.data.filter(i => i.status === 'disconnected').length,
  errors: installations.data.filter(i => i.status === 'error').length
};

console.log('Integration Health:', healthStats);
// Output: { total: 47, active: 42, disconnected: 3, errors: 2 }

Troubleshooting workflows

When customers report “revenue not tracking,” use these diagnostic patterns to quickly identify and resolve issues.

”Revenue not tracking” diagnostics

Step-by-step diagnostic workflow:

async function diagnoseRevenueIssue(sourceId, customerId) {
  // Step 1: Find customer's installation
  const installations = await fetch(
    `https://api.paygentic.io/v0/sources/${sourceId}/installations?subscriptionId=${customerId}`
  );
  
  const installation = installations.data[0];
  
  if (!installation) {
    return {
      issue: 'NO_INSTALLATION',
      action: 'Customer needs to connect their Stripe account',
      resolution: 'Send them the authorization link'
    };
  }
  
  // Step 2: Check installation status
  const detailedInstallation = await fetch(
    `https://api.paygentic.io/v0/sources/${sourceId}/installations/${installation.id}`
  );
  
  const details = await detailedInstallation.json();
  
  if (details.status === 'disconnected') {
    return {
      issue: 'DISCONNECTED',
      action: 'Customer disconnected their integration',
      resolution: 'Guide them through reconnection process',
      disconnectedAt: details.disconnectedAt
    };
  }
  
  if (details.status === 'error') {
    return {
      issue: 'INTEGRATION_ERROR',
      action: 'Technical error occurred',
      resolution: 'Check error message and guide reconnection',
      error: details.errorMessage,
      lastWorking: details.lastSyncAt
    };
  }
  
  // Step 3: Check recent data flow
  const hoursSinceSync = details.lastSyncAt 
    ? (Date.now() - new Date(details.lastSyncAt)) / (1000 * 60 * 60)
    : null;
    
  if (!details.lastSyncAt || hoursSinceSync > 48) {
    return {
      issue: 'NO_RECENT_DATA',
      action: 'No recent data received',
      resolution: 'Check if customer has recent Stripe activity',
      lastSync: details.lastSyncAt
    };
  }
  
  return {
    issue: 'UNKNOWN',
    action: 'Installation appears healthy',
    resolution: 'Check source events and processing status'
  };
}

// Usage
const diagnosis = await diagnoseRevenueIssue('src_123', 'sub_456');
console.log(diagnosis);

Connection failure patterns

Common failure scenarios and their indicators:

Invalid credentials

Symptoms: status: "error", errorMessage: "Invalid API key"

Resolution:

// Customer needs to update their Stripe API key
const installation = await getInstallation(sourceId, installationId);
if (installation.errorMessage?.includes('Invalid API key')) {
  // Guide customer to generate new API key
  console.log('Customer needs to update Stripe credentials');
}

Expired OAuth token

Symptoms: status: "error", errorMessage: "Token expired"

Resolution:

// OAuth token needs refresh
const installation = await getInstallation(sourceId, installationId);
if (installation.errorMessage?.includes('Token expired')) {
  // Trigger OAuth reconnection flow
  console.log('Customer needs to re-authorize OAuth connection');
}

Stripe account issues

Symptoms: status: "error", errorMessage: "Account access denied"

Resolution:

// Stripe account restrictions or permissions
const installation = await getInstallation(sourceId, installationId);
if (installation.errorMessage?.includes('Account access')) {
  console.log('Check Stripe account status and permissions');
}

Error reference

Common status codes

Status	Description	Action Required
active	Integration working properly	None
disconnected	Customer manually disconnected	Guide reconnection
error	Technical failure occurred	Check error message, troubleshoot

Recovery procedures

For credential issues

1. Guide customer to reconnect the source from their subscription portal.

API reference

List installations

GET /sources/{sourceId}/installations

Query parameters:

• subscriptionId (optional) - Filter by customer subscription
• status (optional) - Filter by status: active, disconnected, error
• limit (optional) - Number of results (max 100, default 50)
• offset (optional) - Pagination offset (default 0)

Get installation details

GET /sources/{sourceId}/installations/{installationId}

Returns detailed installation information including error messages, sync timestamps, and configuration.

Update installation

PATCH /sources/{sourceId}/installations/{installationId}

Request body:

{
  "status": "active|disconnected|error",
  "config": {},
  "metadata": {},
  "errorMessage": "Error description"
}

Most installation management should be done through the UI. The API is primarily for monitoring, diagnostics, and automation workflows.

Next steps

• Usage Events → - Understanding how source data becomes billable usage
• API Reference → - Complete API documentation