Implementation Guide: Trigger invoicing milestones based on project phase completion

Hardware Procurement

Software Procurement

Prerequisites

• Client has an active PSA or project management platform (Scoro, BigTime, Kantata, ConnectWise PSA, or HaloPSA) with admin-level access available, OR client has approved procurement of one of these platforms
• Client has an active accounting platform (QuickBooks Online Plus or higher, or Xero Standard or higher) with API access enabled and admin credentials available
• Client has defined project templates with clearly delineated phases/milestones, including milestone names, expected deliverables, and billing amounts per milestone
• Client has documented billing terms for at least their top 5 project types, including: milestone payment percentages, payment terms (Net 15/30/60), and any approval gates required before invoicing
• Client has a modern web browser (Chrome 90+, Edge 90+, Firefox 90+) on all workstations that will access the PSA and accounting platforms
• Reliable internet connectivity (25+ Mbps symmetric minimum) at all client office locations
• Microsoft 365 or Google Workspace accounts for all users who will interact with the system (for SSO and notification delivery)
• Client has designated a Project Operations Lead (typically a senior PM or operations manager) who will own the business rules and serve as the primary point of contact during implementation
• Client finance team has confirmed the chart of accounts, income categories, and tax codes to be used for automated invoices
• For clients subject to ASC 606: written confirmation from the client's accountant or CFO on how revenue recognition should differ from billing events, and whether the automation should create the invoice in draft or approved status
• MSP has provisioned or has access to a VM or VPS (2 vCPU, 4 GB RAM, 40 GB SSD minimum) for hosting n8n, OR has an active Zapier Team / Make Pro subscription
• MSP technician assigned to the project has experience with REST APIs, webhook configuration, and at least one of: n8n, Zapier, Make, or Power Automate
• Client has provided a list of all active projects that will be migrated to the new milestone billing workflow, including current phase status and outstanding unbilled milestones

Installation Steps

...

Step 1: Discovery & Business Process Mapping

Conduct a 2–3 hour discovery workshop with the client's project managers, finance team, and operations lead. Map the current invoicing workflow from project kickoff to payment receipt. Document all project types, phase structures, billing terms, approval gates, and exception handling (e.g., scope changes, partial completions, cancellations). Output a formal Business Process Document (BPD) and Automation Rules Specification.

Step 2: Configure PSA Platform — Project Templates & Milestones

In the client's PSA platform (Scoro, BigTime, or equivalent), create or update project templates with standardized phase structures that will serve as automation triggers. Each phase must have: a unique phase name, a billing type (milestone/fixed/T&M), a milestone amount or percentage, and a status field with defined values (Not Started, In Progress, Complete, On Hold). Enable webhook or API notification capabilities on the PSA platform.

• Scoro: Navigate to Settings > Site Settings > Integrations > Webhooks
• Add a new webhook with the following configuration:
• Event: Project Phase Status Changed
• URL: https://your-n8n-domain.com/webhook/scoro-phase-complete
• Method: POST
• Content-Type: application/json
• Secret: [generate a 32-character random string and store in password manager]
• BigTime: Navigate to My Company > Integrations > API Settings
• Enable REST API access
• Generate an API key and store securely
• Note: BigTime uses polling rather than webhooks, so n8n will poll the API on a schedule

Step 3: Configure Accounting Platform — Invoice Templates & API Access

In QuickBooks Online (or Xero), create invoice templates that match the client's branding and include all required fields for milestone invoices. Configure API access by creating an app in the developer portal, obtaining OAuth 2.0 credentials, and setting up the necessary scopes for invoice creation.

# QuickBooks Online API Setup:
# 1. Go to https://developer.intuit.com/app/developer/qbo/docs/get-started
# 2. Create a new app (select 'Accounting' as the scope)
# 3. In the app settings, configure:
#    - Redirect URI: https://your-n8n-domain.com/rest/oauth2-credential/callback
#    - Scopes: com.intuit.quickbooks.accounting (read/write)
# 4. Note the Client ID and Client Secret
# 5. Store credentials in the MSP's password vault

# Xero API Setup:
# 1. Go to https://developer.xero.com/app/manage
# 2. Create a new app (Web App type)
# 3. Configure:
#    - Redirect URI: https://your-n8n-domain.com/rest/oauth2-credential/callback
#    - Scopes: accounting.transactions, accounting.contacts
# 4. Note the Client ID and Client Secret

Step 4: Deploy n8n Automation Server (Self-Hosted)

Provision and configure the n8n server that will serve as the automation middleware. This server receives webhook events from the PSA, evaluates business rules, and creates invoices in the accounting platform. Deploy using Docker Compose on the provisioned VM for easy management and updates.

# SSH into the provisioned VM
ssh adminuser@your-n8n-server-ip

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker and Docker Compose
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER

# Create n8n directory structure
sudo mkdir -p /opt/n8n/data
sudo mkdir -p /opt/n8n/config
cd /opt/n8n

# Create Docker Compose file
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports:
      - '5678:5678'
    environment:
      - N8N_HOST=your-n8n-domain.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://your-n8n-domain.com/
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=msp-admin
      - N8N_BASIC_AUTH_PASSWORD=<generate-strong-password-here>
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=<generate-db-password-here>
      - N8N_ENCRYPTION_KEY=<generate-32-char-encryption-key>
      - GENERIC_TIMEZONE=America/New_York
      - N8N_LOG_LEVEL=info
      - N8N_DIAGNOSTICS_ENABLED=false
    volumes:
      - ./data:/home/node/.n8n
  postgres:
    image: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=<same-db-password-as-above>
      - POSTGRES_DB=n8n
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
EOF

# Start n8n
sudo docker compose up -d

# Verify containers are running
sudo docker compose ps

# Check n8n logs
sudo docker compose logs -f n8n

Step 5: Configure SSL and Reverse Proxy for n8n

Set up Nginx as a reverse proxy with Let's Encrypt SSL certificates to secure the n8n webhook endpoint. All webhook URLs must use HTTPS in production. Alternatively, use Cloudflare Tunnel for zero-trust access without opening inbound ports.

# Install Nginx and Certbot
sudo apt install -y nginx certbot python3-certbot-nginx

# Create Nginx configuration
sudo cat > /etc/nginx/sites-available/n8n << 'EOF'
server {
    listen 80;
    server_name your-n8n-domain.com;

    location / {
        proxy_pass http://localhost:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        chunked_transfer_encoding off;
        proxy_buffering off;
    }
}
EOF

# Enable the site
sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Obtain SSL certificate
sudo certbot --nginx -d your-n8n-domain.com --non-interactive --agree-tos -m msp-alerts@yourdomain.com

# Verify auto-renewal
sudo certbot renew --dry-run

Step 6: Build the Core Milestone-to-Invoice Automation Workflow in n8n

Create the primary n8n workflow that receives webhook events from the PSA, validates the event data against business rules, looks up client and milestone billing details, and creates a draft invoice in the accounting platform. This is the heart of the automation.

Step 7: Configure PSA Webhook to n8n Connection

Register the n8n webhook URL in the PSA platform so that phase completion events are automatically sent to the automation engine. Test the webhook connection with a sample event to verify connectivity and payload format.

• For Scoro: Go to Settings > Site Settings > Integrations > Webhooks
• Add webhook — Name: n8n Milestone Invoice Trigger | URL: https://your-n8n-domain.com/webhook/scoro-phase-complete | Events: project.modified (or project_phase.status_changed if available) | Secret: <the-secret-from-step-2>
• Save and click 'Test' to send a sample payload
• For BigTime (polling-based): In n8n, the workflow uses a Schedule Trigger node instead of a Webhook node
• Configure Schedule Trigger to poll the BigTime API every 10 minutes: Schedule Trigger > Rule: Every 10 minutes
• HTTP Request node: GET https://iq.bigtime.net/BigtimeData/api/v2/project/{id}/phases with Headers: X-Auth-Token: <bigtime-api-key>, X-Auth-Realm: <bigtime-firm-id>

Step 8: Configure QuickBooks Online Integration in n8n

Set up the QuickBooks Online credential in n8n using OAuth 2.0, and configure the invoice creation node with the correct customer mapping, line items, and tax settings. Test with a sample invoice creation.

• In n8n: Go to Credentials > Add Credential > QuickBooks
• Enter: Client ID: <from Step 3>, Client Secret: <from Step 3>, Environment: Production
• Click 'Connect' — this opens the Intuit OAuth consent screen
• Authorize the connection for the client's QBO company
• Test the connection: Create a simple test workflow with a Manual Trigger > QuickBooks node
• Operation: Get All Customers — Execute and verify you see the client's customer list
• For Xero: Go to Credentials > Add Credential > Xero
• Enter Client ID and Client Secret from Step 3
• Click 'Connect' and authorize
• Select the correct Xero Organization if multiple exist

Step 9: Build Client and Project Mapping Table

Create a mapping configuration that links PSA project phases to accounting platform customer IDs, invoice line items, amounts, and payment terms. This mapping table is the bridge between the two systems and encodes the client's billing rules.

# In n8n, create a static data configuration or use a Google Sheet / Airtable as a lightweight config database
# The mapping table should contain:

# Option A: Use n8n Static Data (simplest for <50 projects)
# In the workflow's Function node, define the mapping:

const milestoneConfig = {
  'project-template-web-design': {
    phases: {
      'Discovery': { pct: 25, qbo_item_id: '1', payment_terms: 'Net 30' },
      'Design': { pct: 25, qbo_item_id: '1', payment_terms: 'Net 30' },
      'Development': { pct: 35, qbo_item_id: '1', payment_terms: 'Net 30' },
      'Launch': { pct: 15, qbo_item_id: '1', payment_terms: 'Net 15' }
    }
  },
  'project-template-consulting': {
    phases: {
      'Assessment': { pct: 30, qbo_item_id: '2', payment_terms: 'Net 30' },
      'Strategy': { pct: 30, qbo_item_id: '2', payment_terms: 'Net 30' },
      'Implementation': { pct: 40, qbo_item_id: '2', payment_terms: 'Net 30' }
    }
  }
};

# Option B: Use Google Sheets as config (better for >50 projects, client-editable)
# Create a Google Sheet with columns:
# ProjectTemplate | PhaseName | BillingPct | QBO_ItemID | PaymentTerms | RequiresApproval
# Share with the n8n service account

Step 10: Implement Approval Gate (Optional but Recommended)

For clients requiring a human review before invoices are sent, add an approval workflow step. When a milestone is triggered, the system creates a draft invoice and sends a Slack or Teams notification (or email) to the designated approver. The approver clicks 'Approve' to finalize and send the invoice, or 'Reject' to flag for review.

• In n8n, add a Slack or Microsoft Teams node after the invoice draft creation
• Slack notification configuration — Channel: #billing-approvals
• Message template fields: Project ({{$json.projectName}}), Client ({{$json.clientName}}), Phase Completed ({{$json.phaseName}}), Invoice Amount (${{$json.invoiceAmount}}), QBO Draft Invoice # ({{$json.qboInvoiceNumber}})
• Include a review link: https://your-qbo-url.com/invoice/{{$json.qboInvoiceId}}
• React with ✅ to approve or ❌ to flag for review
• For email-based approval: Use n8n's Email (IMAP) node with a unique subject line, or use a simple webhook-based approve/reject URL pair

Step 11: Configure Monitoring, Logging, and Error Handling

Set up error notification workflows in n8n so the MSP is immediately alerted if any automation execution fails. Configure execution logging for audit trail purposes and set up health check monitoring on the n8n server.

cat > /opt/n8n/healthcheck.sh << 'EOF'
#!/bin/bash
HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' https://your-n8n-domain.com/healthz)
if [ "$HTTP_CODE" != "200" ]; then
  curl -X POST -H 'Content-type: application/json' \
    --data '{"text":"🚨 n8n server is DOWN (HTTP $HTTP_CODE)"}' \
    https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
fi
EOF
chmod +x /opt/n8n/healthcheck.sh
(crontab -l 2>/dev/null; echo '*/5 * * * * /opt/n8n/healthcheck.sh') | crontab -

Step 12: Data Migration — Import Active Projects and Outstanding Milestones

For clients with existing in-flight projects, import the current project data, phase statuses, and outstanding milestone billing amounts into the PSA platform. Configure the automation to recognize which milestones have already been billed versus those pending.

# Export current project data from existing systems (spreadsheets, old PM tool, etc.)
# Create a CSV with columns:
# ProjectName, ClientName, QBO_CustomerID, ProjectTemplate, PhaseNumber, PhaseName, Status, MilestoneAmount, AlreadyBilled (Y/N)

# Import into PSA platform:
# Scoro: Settings > Data Import > Projects (CSV upload)
# BigTime: Use the BigTime API for bulk project creation:
# POST https://iq.bigtime.net/BigtimeData/api/v2/project
# Content-Type: application/json
# X-Auth-Token: <api-key>
# Body: { "ProjectNm": "...", "ClientId": "...", ... }

# Mark already-billed milestones to prevent double-invoicing:
# In the n8n mapping table or PSA custom fields, flag phases where AlreadyBilled = Y
# The automation workflow checks this flag before creating an invoice

Step 13: User Training and Go-Live

Conduct training sessions for three user groups: (1) Project Managers — how phase completion triggers work and what they need to do differently, (2) Finance Team — how to review and approve draft invoices, handle exceptions, and reconcile, (3) Operations Lead — how to manage the mapping table, add new project templates, and troubleshoot. Then activate the automation in production.

Custom AI Components

Milestone Phase Completion Webhook Handler

Type: workflow n8n workflow node that receives incoming webhook events from the PSA platform when a project phase status changes. It validates the webhook signature, extracts the relevant data (project ID, phase name, new status, client ID), and passes it to the next processing stage. Handles both real-time webhooks (Scoro) and polling-based detection (BigTime).

Implementation

For Scoro (Real-Time Webhook)

• Node Type: Webhook
• HTTP Method: POST
• Path: /scoro-phase-complete
• Authentication: Header Auth
• Header Name: X-Webhook-Secret
• Header Value: {{$credentials.scoroWebhookSecret}}
• Response Mode: Last Node
• Response Code: 200

const payload = $input.first().json;

// Validate the event type
if (!payload || !payload.data || !payload.data.project_id) {
  throw new Error('Invalid webhook payload: missing project_id');
}

// Extract relevant fields from Scoro webhook
const output = {
  source: 'scoro',
  eventType: payload.event || 'project.modified',
  projectId: payload.data.project_id,
  projectName: payload.data.project_name || '',
  phaseName: payload.data.phase_name || payload.data.activity_name || '',
  phaseStatus: payload.data.phase_status || payload.data.status || '',
  clientId: payload.data.company_id || '',
  clientName: payload.data.company_name || '',
  modifiedBy: payload.data.modified_by || '',
  modifiedAt: payload.data.modified_date || new Date().toISOString(),
  rawPayload: JSON.stringify(payload)
};

// Only proceed if the status indicates completion
const completionStatuses = ['completed', 'complete', 'done', 'finished', 'closed'];
if (!completionStatuses.includes(output.phaseStatus.toLowerCase())) {
  // Not a completion event — stop processing
  return [];
}

return [output];

For BigTime (Polling-Based)

• Node Type: Schedule Trigger
• Rule: Every 10 Minutes

GET https://iq.bigtime.net/BigtimeData/api/v2/project/phases?UpdatedAfter={{$now.minus(15, 'minutes').toISO()}}
X-Auth-Token: {{$credentials.bigtimeApiKey}}
X-Auth-Realm: {{$credentials.bigtimeFirmId}}
Content-Type: application/json

const items = $input.all();
const processedKey = 'processedPhaseCompletions';
const staticData = $getWorkflowStaticData('global');

if (!staticData[processedKey]) {
  staticData[processedKey] = {};
}

const newCompletions = [];

for (const item of items) {
  const phase = item.json;
  const uniqueKey = `${phase.ProjectId}-${phase.PhaseId}-${phase.Status}`;
  
  if (phase.Status === 'Completed' && !staticData[processedKey][uniqueKey]) {
    staticData[processedKey][uniqueKey] = new Date().toISOString();
    newCompletions.push({
      source: 'bigtime',
      eventType: 'phase.completed',
      projectId: phase.ProjectId,
      projectName: phase.ProjectNm,
      phaseName: phase.PhaseNm,
      phaseStatus: 'completed',
      clientId: phase.ClientId,
      clientName: phase.ClientNm,
      modifiedAt: phase.UpdatedDt,
      rawPayload: JSON.stringify(phase)
    });
  }
}

// Prune entries older than 30 days to prevent memory bloat
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
for (const [key, timestamp] of Object.entries(staticData[processedKey])) {
  if (timestamp < thirtyDaysAgo) {
    delete staticData[processedKey][key];
  }
}

return newCompletions;

Billing Rules Engine

Type: workflow n8n Code node that evaluates the completed milestone against the client's billing configuration to determine: (1) whether an invoice should be created, (2) the invoice amount, (3) the line item details, (4) payment terms, and (5) whether approval is required. This is the deterministic 'brain' of the automation that encodes all business rules.

Implementation:

// Billing Rules Engine
// Receives: phase completion event from webhook handler
// Outputs: invoice specification or skip signal

const event = $input.first().json;

// ===== CONFIGURATION: BILLING RULES =====
// In production, load this from Google Sheets, Airtable, or a database
// For initial deployment, define inline and update as needed

const billingConfig = {
  projectTemplates: {
    'web-design': {
      defaultPaymentTerms: 'Net 30',
      requiresApproval: false,
      phases: {
        'Discovery & Research': {
          billingPercentage: 25,
          qboItemId: '1',  // Service item ID in QuickBooks
          qboItemName: 'Web Design Services',
          description: 'Discovery & Research phase - Web Design project',
          taxable: true,
          requiresApproval: false
        },
        'Design & Wireframes': {
          billingPercentage: 25,
          qboItemId: '1',
          qboItemName: 'Web Design Services',
          description: 'Design & Wireframes phase - Web Design project',
          taxable: true,
          requiresApproval: false
        },
        'Development & Build': {
          billingPercentage: 35,
          qboItemId: '1',
          qboItemName: 'Web Design Services',
          description: 'Development & Build phase - Web Design project',
          taxable: true,
          requiresApproval: true  // Largest milestone, require review
        },
        'Launch & Handoff': {
          billingPercentage: 15,
          qboItemId: '1',
          qboItemName: 'Web Design Services',
          description: 'Launch & Handoff phase - Web Design project',
          taxable: true,
          requiresApproval: false
        }
      }
    },
    'consulting-engagement': {
      defaultPaymentTerms: 'Net 30',
      requiresApproval: true,
      phases: {
        'Assessment': {
          billingPercentage: 30,
          qboItemId: '2',
          qboItemName: 'Consulting Services',
          description: 'Assessment phase - Consulting engagement',
          taxable: false,
          requiresApproval: true
        },
        'Strategy Development': {
          billingPercentage: 30,
          qboItemId: '2',
          qboItemName: 'Consulting Services',
          description: 'Strategy Development phase - Consulting engagement',
          taxable: false,
          requiresApproval: true
        },
        'Implementation Support': {
          billingPercentage: 40,
          qboItemId: '2',
          qboItemName: 'Consulting Services',
          description: 'Implementation Support phase - Consulting engagement',
          taxable: false,
          requiresApproval: true
        }
      }
    }
  },
  
  // Client-to-QBO customer mapping
  // Key: PSA client ID, Value: QBO customer ID
  clientMapping: {
    'psa-client-001': { qboCustomerId: '123', qboCustomerName: 'Acme Corp' },
    'psa-client-002': { qboCustomerId: '456', qboCustomerName: 'Globex Inc' },
    // Add more client mappings as needed
  },
  
  // Project-to-template mapping (links specific projects to templates)
  // Key: PSA project ID, Value: { templateKey, contractAmount }
  projectMapping: {
    'proj-001': { templateKey: 'web-design', contractAmount: 20000 },
    'proj-002': { templateKey: 'consulting-engagement', contractAmount: 50000 },
    // Add more project mappings as needed
  }
};

// ===== RULES ENGINE =====

// 1. Look up the project configuration
const projectConfig = billingConfig.projectMapping[event.projectId];
if (!projectConfig) {
  return [{
    json: {
      action: 'SKIP',
      reason: `Project ${event.projectId} (${event.projectName}) not found in billing configuration. May be a non-billable project or needs to be added to the mapping.`,
      event: event,
      severity: 'WARNING'
    }
  }];
}

// 2. Look up the template and phase
const template = billingConfig.projectTemplates[projectConfig.templateKey];
if (!template) {
  return [{
    json: {
      action: 'ERROR',
      reason: `Template '${projectConfig.templateKey}' not found in billing configuration.`,
      event: event,
      severity: 'ERROR'
    }
  }];
}

const phaseConfig = template.phases[event.phaseName];
if (!phaseConfig) {
  return [{
    json: {
      action: 'SKIP',
      reason: `Phase '${event.phaseName}' not found in template '${projectConfig.templateKey}'. May be a non-billable phase.`,
      event: event,
      severity: 'INFO'
    }
  }];
}

// 3. Look up the client in accounting
const clientConfig = billingConfig.clientMapping[event.clientId];
if (!clientConfig) {
  return [{
    json: {
      action: 'ERROR',
      reason: `Client ${event.clientId} (${event.clientName}) not found in QBO customer mapping. Must be added before invoicing.`,
      event: event,
      severity: 'ERROR'
    }
  }];
}

// 4. Calculate invoice amount
const invoiceAmount = (projectConfig.contractAmount * phaseConfig.billingPercentage) / 100;

// 5. Determine if approval is needed
const requiresApproval = template.requiresApproval || phaseConfig.requiresApproval;

// 6. Build the invoice specification
const invoiceSpec = {
  action: 'CREATE_INVOICE',
  requiresApproval: requiresApproval,
  invoice: {
    customerId: clientConfig.qboCustomerId,
    customerName: clientConfig.qboCustomerName,
    invoiceDate: new Date().toISOString().split('T')[0],
    dueDate: calculateDueDate(template.defaultPaymentTerms),
    paymentTerms: template.defaultPaymentTerms,
    lineItems: [
      {
        itemId: phaseConfig.qboItemId,
        itemName: phaseConfig.qboItemName,
        description: `${phaseConfig.description}\nProject: ${event.projectName}\nPhase completed: ${event.modifiedAt}`,
        quantity: 1,
        unitPrice: invoiceAmount,
        taxable: phaseConfig.taxable
      }
    ],
    memo: `Auto-generated from milestone completion. Project: ${event.projectName}, Phase: ${event.phaseName}, Completed by: ${event.modifiedBy}`,
    customFields: {
      projectId: event.projectId,
      projectName: event.projectName,
      phaseName: event.phaseName,
      automationId: `auto-${Date.now()}`
    }
  },
  auditTrail: {
    triggeredAt: new Date().toISOString(),
    triggeredBy: 'milestone-automation',
    sourceEvent: event,
    billingRule: {
      template: projectConfig.templateKey,
      phase: event.phaseName,
      percentage: phaseConfig.billingPercentage,
      contractAmount: projectConfig.contractAmount,
      calculatedAmount: invoiceAmount
    }
  }
};

return [{ json: invoiceSpec }];

// ===== HELPER FUNCTIONS =====

function calculateDueDate(terms) {
  const today = new Date();
  const daysMap = {
    'Net 15': 15,
    'Net 30': 30,
    'Net 45': 45,
    'Net 60': 60,
    'Due on Receipt': 0
  };
  const days = daysMap[terms] || 30;
  today.setDate(today.getDate() + days);
  return today.toISOString().split('T')[0];
}

Integration Notes

• After this Code node, add an IF node that routes based on the action field: CREATE_INVOICE → proceed to invoice creation; SKIP → log and end (optionally notify via Slack for WARNINGs); ERROR → trigger error notification to MSP and client ops lead
• The requiresApproval field routes to either the direct invoice creation path or the approval gate path
• The auditTrail object should be stored (e.g., in a Google Sheet or database) for compliance reporting

QuickBooks Invoice Creator

Type: integration n8n workflow segment that takes the invoice specification from the Billing Rules Engine and creates a draft invoice in QuickBooks Online via the QBO API. Handles line item creation, customer association, payment terms, and memo fields. Returns the created invoice ID and number for downstream notification.

HTTP Request Node: Create QBO Invoice

• Method: POST
• URL: https://quickbooks.api.intuit.com/v3/company/{{$credentials.qboCompanyId}}/invoice
• Authentication: OAuth 2.0 (QBO credential configured in Step 8)
• Headers: Content-Type: application/json
• Headers: Accept: application/json

# HTTP Request Node POST to QBO Invoice API

{
  "Line": [
    {
      "Amount": {{$json.invoice.lineItems[0].unitPrice}},
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": {
          "value": "{{$json.invoice.lineItems[0].itemId}}"
        },
        "UnitPrice": {{$json.invoice.lineItems[0].unitPrice}},
        "Qty": 1,
        "TaxCodeRef": {
          "value": "{{$json.invoice.lineItems[0].taxable ? 'TAX' : 'NON'}}"
        }
      },
      "Description": "{{$json.invoice.lineItems[0].description}}"
    }
  ],
  "CustomerRef": {
    "value": "{{$json.invoice.customerId}}"
  },
  "TxnDate": "{{$json.invoice.invoiceDate}}",
  "DueDate": "{{$json.invoice.dueDate}}",
  "PrivateNote": "{{$json.invoice.memo}}",
  "CustomerMemo": {
    "value": "Thank you for your business. This invoice was generated upon completion of project milestone: {{$json.invoice.customFields.phaseName}}."
  },
  "SalesTermRef": {
    "value": "{{$json.invoice.paymentTerms === 'Net 30' ? '3' : $json.invoice.paymentTerms === 'Net 15' ? '2' : $json.invoice.paymentTerms === 'Net 60' ? '5' : '3'}}"
  },
  "EmailStatus": "NotSet"
}

Response Processing (Code Node after HTTP Request)

// parse QBO API response and build result object

const response = $input.first().json;
const invoiceSpec = $('Billing Rules Engine').first().json;

const result = {
  success: true,
  qboInvoiceId: response.Invoice.Id,
  qboInvoiceNumber: response.Invoice.DocNumber,
  invoiceAmount: response.Invoice.TotalAmt,
  customerName: response.Invoice.CustomerRef.name,
  dueDate: response.Invoice.DueDate,
  qboInvoiceUrl: `https://app.qbo.intuit.com/app/invoice?txnId=${response.Invoice.Id}`,
  requiresApproval: invoiceSpec.requiresApproval,
  auditTrail: invoiceSpec.auditTrail,
  createdAt: new Date().toISOString()
};

return [{ json: result }];

For Xero (Alternative)

• Method: POST
• URL: https://api.xero.com/api.xro/2.0/Invoices
• Headers: Xero-Tenant-Id: {{$credentials.xeroTenantId}}

{
  "Invoices": [{
    "Type": "ACCREC",
    "Contact": { "ContactID": "{{$json.invoice.customerId}}" },
    "Date": "{{$json.invoice.invoiceDate}}",
    "DueDate": "{{$json.invoice.dueDate}}",
    "Status": "DRAFT",
    "LineItems": [{
      "Description": "{{$json.invoice.lineItems[0].description}}",
      "Quantity": 1,
      "UnitAmount": {{$json.invoice.lineItems[0].unitPrice}},
      "AccountCode": "200",
      "TaxType": "{{$json.invoice.lineItems[0].taxable ? 'OUTPUT' : 'NONE'}}"
    }],
    "Reference": "{{$json.invoice.customFields.automationId}}"
  }]
}

Notification and Audit Logger

Type: workflow n8n workflow segment that sends notifications to relevant stakeholders after an invoice is created (or after an error occurs) and logs all automation events to a persistent audit trail for compliance purposes (ASC 606, SOX). Supports Slack, Microsoft Teams, and email notifications.

Part 1: Stakeholder Notification

Slack Notification Node Configuration

• Node Type: Slack
• Resource: Message
• Operation: Send
• Channel: #billing-notifications (for successful invoices) OR #billing-approvals (if approval required)

Microsoft Teams Notification (Alternative)

• Node Type: Microsoft Teams
• Resource: Chat Message or Channel Message
• Channel: Billing Automation
• Message: (same content as Slack, formatted with Teams markdown)

Email Notification (Fallback)

• Node Type: Send Email (SMTP)
• To: finance-team@clientdomain.com
• Subject: Milestone Invoice #{{$json.qboInvoiceNumber}} Created - {{$json.customerName}} - ${{$json.invoiceAmount}}
• Body: HTML version of the notification content above

Part 2: Audit Trail Logger

Log every automation event to a Google Sheet (simple) or PostgreSQL table (robust) for compliance.

Option A: Google Sheets Audit Log

• Node Type: Google Sheets
• Operation: Append Row
• Sheet: 'Invoice Automation Audit Log'

// Code node to format audit row
const event = $input.first().json;

return [{
  json: {
    Timestamp: new Date().toISOString(),
    EventType: 'INVOICE_CREATED',
    ProjectId: event.auditTrail.sourceEvent.projectId,
    ProjectName: event.auditTrail.sourceEvent.projectName,
    ClientName: event.customerName,
    PhaseName: event.auditTrail.sourceEvent.phaseName,
    BillingTemplate: event.auditTrail.billingRule.template,
    BillingPercentage: event.auditTrail.billingRule.percentage,
    ContractAmount: event.auditTrail.billingRule.contractAmount,
    InvoiceAmount: event.invoiceAmount,
    QBOInvoiceId: event.qboInvoiceId,
    QBOInvoiceNumber: event.qboInvoiceNumber,
    DueDate: event.dueDate,
    RequiredApproval: event.requiresApproval,
    TriggeredBy: event.auditTrail.triggeredBy,
    CompletedBy: event.auditTrail.sourceEvent.modifiedBy,
    AutomationId: event.auditTrail.billingRule ? 'auto-' + event.qboInvoiceId : '',
    Status: 'DRAFT_CREATED'
  }
}];

Option B: PostgreSQL Audit Log (for higher volume / SOX compliance)

-- Create audit table and indexes (run once during setup)

-- Create audit table (run once during setup)
CREATE TABLE IF NOT EXISTS invoice_automation_audit (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMPTZ DEFAULT NOW(),
  event_type VARCHAR(50) NOT NULL,
  project_id VARCHAR(100),
  project_name VARCHAR(255),
  client_name VARCHAR(255),
  phase_name VARCHAR(255),
  billing_template VARCHAR(100),
  billing_percentage DECIMAL(5,2),
  contract_amount DECIMAL(12,2),
  invoice_amount DECIMAL(12,2),
  qbo_invoice_id VARCHAR(50),
  qbo_invoice_number VARCHAR(50),
  due_date DATE,
  requires_approval BOOLEAN,
  triggered_by VARCHAR(100),
  completed_by VARCHAR(255),
  status VARCHAR(50),
  raw_event JSONB
);

CREATE INDEX idx_audit_project ON invoice_automation_audit(project_id);
CREATE INDEX idx_audit_timestamp ON invoice_automation_audit(timestamp);
CREATE INDEX idx_audit_client ON invoice_automation_audit(client_name);

• Node Type: Postgres
• Operation: Insert
• Table: invoice_automation_audit
• Map all fields from the Code node output above

Part 3: Error Notification (for failed executions)

• Node Type: Slack (connected to Error Trigger workflow)

Duplicate Invoice Prevention Guard

Type: workflow A critical safety component that prevents the same milestone from generating multiple invoices. This can happen due to webhook retries, PSA status toggling (complete → in progress → complete), or system errors. The guard checks for existing invoices before creating a new one. Implementation:

Duplicate Invoice Prevention — n8n Code Node

• Place this node AFTER the Billing Rules Engine and BEFORE the QuickBooks Invoice Creator.

// Duplicate Invoice Prevention Guard
// Checks multiple sources to ensure this milestone hasn't already been invoiced

const invoiceSpec = $input.first().json;

if (invoiceSpec.action !== 'CREATE_INVOICE') {
  // Not an invoice creation — pass through
  return [$input.first()];
}

const projectId = invoiceSpec.auditTrail.sourceEvent.projectId;
const phaseName = invoiceSpec.auditTrail.sourceEvent.phaseName;
const uniqueKey = `${projectId}::${phaseName}`;

// Check 1: n8n Static Data (in-memory dedup)
const staticData = $getWorkflowStaticData('global');
if (!staticData.invoicedMilestones) {
  staticData.invoicedMilestones = {};
}

if (staticData.invoicedMilestones[uniqueKey]) {
  const previousInvoice = staticData.invoicedMilestones[uniqueKey];
  return [{
    json: {
      action: 'SKIP',
      reason: `DUPLICATE PREVENTED: Milestone '${phaseName}' for project '${projectId}' was already invoiced on ${previousInvoice.date}. QBO Invoice #: ${previousInvoice.invoiceNumber}`,
      severity: 'WARNING',
      previousInvoice: previousInvoice
    }
  }];
}

// Check 2: Query QuickBooks for existing invoice with this project+phase reference
// This is a secondary check in case static data was lost (server restart, etc.)
// We use the PrivateNote field which contains our automation memo
// This check is performed by a subsequent HTTP Request node — flag it here

const output = {
  ...invoiceSpec,
  _dedup: {
    uniqueKey: uniqueKey,
    searchQuery: `SELECT * FROM Invoice WHERE PrivateNote LIKE '%${projectId}%' AND PrivateNote LIKE '%${phaseName}%'`,
    passed_memory_check: true
  }
};

return [{ json: output }];

Secondary QBO Query Check (HTTP Request Node after Code Node)

• Method: GET
• URL: https://quickbooks.api.intuit.com/v3/company/{{$credentials.qboCompanyId}}/query?query=SELECT * FROM Invoice WHERE PrivateNote LIKE '%{{$json.auditTrail.sourceEvent.projectId}}%' AND PrivateNote LIKE '%{{encodeURIComponent($json.auditTrail.sourceEvent.phaseName)}}%'
• Authentication: OAuth 2.0 (QBO credential)

Post-QBO-Check Code Node

const qboResponse = $input.first().json;
const invoiceSpec = $('Duplicate Guard Code').first().json;

const existingInvoices = qboResponse?.QueryResponse?.Invoice || [];

if (existingInvoices.length > 0) {
  // Invoice already exists in QBO — duplicate!
  const existing = existingInvoices[0];
  return [{
    json: {
      action: 'SKIP',
      reason: `DUPLICATE PREVENTED (QBO check): Invoice #${existing.DocNumber} already exists for this milestone. Amount: $${existing.TotalAmt}. Created: ${existing.MetaData.CreateTime}`,
      severity: 'WARNING',
      existingInvoice: {
        id: existing.Id,
        number: existing.DocNumber,
        amount: existing.TotalAmt
      }
    }
  }];
}

// No duplicate found — proceed with invoice creation
// Also store in static data for future in-memory checks
const staticData = $getWorkflowStaticData('global');
if (!staticData.invoicedMilestones) {
  staticData.invoicedMilestones = {};
}
// Note: We'll update this AFTER successful creation in the post-creation node

return [{ json: invoiceSpec }];

Post-Creation: Update Dedup Store

• After the QBO Invoice Creator succeeds, add this Code Node:

const result = $input.first().json;
const invoiceSpec = $('Billing Rules Engine').first().json;

const staticData = $getWorkflowStaticData('global');
if (!staticData.invoicedMilestones) {
  staticData.invoicedMilestones = {};
}

const uniqueKey = `${invoiceSpec.auditTrail.sourceEvent.projectId}::${invoiceSpec.auditTrail.sourceEvent.phaseName}`;
staticData.invoicedMilestones[uniqueKey] = {
  invoiceId: result.qboInvoiceId,
  invoiceNumber: result.qboInvoiceNumber,
  amount: result.invoiceAmount,
  date: new Date().toISOString()
};

return [$input.first()];

Testing & Validation

• TEST 1 — Webhook Connectivity: In the PSA platform (Scoro/BigTime), change a test project's phase from 'In Progress' to 'Complete'. Verify within 60 seconds (Scoro webhook) or 15 minutes (BigTime polling) that the n8n execution log shows a successful trigger with the correct project ID, phase name, and client ID in the payload.
• TEST 2 — Billing Rules Engine Accuracy: Create 5 test scenarios covering different project templates and phases. For each, manually calculate the expected invoice amount (contract amount × billing percentage). Run each through the automation and verify the Billing Rules Engine output matches the manual calculation exactly (to the penny).
• TEST 3 — QuickBooks Invoice Creation: Trigger a milestone completion for a mapped test project. Verify that a DRAFT invoice appears in QuickBooks Online with: (a) correct customer name, (b) correct line item description, (c) correct amount, (d) correct due date based on payment terms, (e) correct memo containing project and phase details. Cross-check all fields against the billing rules configuration.
• TEST 4 — Duplicate Prevention: Trigger the same milestone completion event twice (e.g., toggle a phase status back and forth, or resend the webhook manually). Verify that only ONE invoice is created. Check the n8n execution log to confirm the second attempt was caught by the Duplicate Invoice Prevention Guard with a clear 'DUPLICATE PREVENTED' message.
• TEST 5 — Unknown Project/Phase Handling: Trigger a phase completion for a project that is NOT in the billing configuration mapping table. Verify that no invoice is created, the workflow logs a SKIP event with an appropriate warning message, and a notification is sent to the MSP/ops lead alerting them to add the mapping.
• TEST 6 — Error Notification: Temporarily invalidate the QuickBooks OAuth token (e.g., revoke access in the QBO developer portal). Trigger a milestone completion. Verify that: (a) the workflow fails gracefully without crashing n8n, (b) the error trigger workflow fires, (c) a Slack/email notification is received by the MSP within 5 minutes with the error details and execution link.
• TEST 7 — Approval Gate: For a milestone configured with requiresApproval=true, trigger a phase completion. Verify that: (a) a draft invoice is created in QBO, (b) a notification is sent to the #billing-approvals channel with a link to the invoice, (c) the invoice remains in Draft status until manually approved and sent by the finance team.
• TEST 8 — Audit Trail Completeness: After running tests 1–7, check the audit log (Google Sheet or PostgreSQL table). Verify that every automation event is logged with all required fields: timestamp, project ID, client name, phase name, invoice amount, QBO invoice number, triggered-by, and status. Verify that SKIP and ERROR events are also logged, not just successful invoice creations.
• TEST 9 — End-to-End Full Cycle: Execute a complete project lifecycle in the PSA: create a project using a standard template, complete Phase 1 → verify invoice 1 is created, complete Phase 2 → verify invoice 2 is created, complete Phase 3 → verify invoice 3 is created. Confirm total invoiced amount equals the contract amount. Confirm all three invoices appear in QBO and the audit log.
• TEST 10 — Performance and Reliability: If the client has >20 active projects, simulate 5 near-simultaneous phase completions (within a 1-minute window). Verify that all 5 invoices are created correctly without duplicates, errors, or missed triggers. Check the n8n server CPU and memory utilization during the burst to confirm it stays within acceptable limits (CPU <80%, RAM <90%).
• TEST 11 — Parallel Run Validation: During the 2-week parallel run period, compare every automated invoice against the manually-created invoice for the same milestone. Document any discrepancies in amount, customer mapping, payment terms, line item descriptions, or tax codes. Zero discrepancies over 10+ invoices required before ending the parallel run.

Client Handoff

Client Handoff Checklist

Training Sessions Delivered (with recordings provided):

Documentation Delivered:

• System Architecture Diagram: Visual showing PSA → n8n → QuickBooks flow with all connection points
• Billing Rules Reference Document: Complete table of all project templates, phases, billing percentages, payment terms, and approval requirements
• Client-to-QBO Customer Mapping Table: Current mapping of all PSA clients to QBO customer IDs
• Runbook: Adding a New Project Template: Step-by-step guide for the operations lead to add new billing rules
• Runbook: Adding a New Client Mapping: Step-by-step guide for mapping a new client
• Troubleshooting Guide: Common issues (webhook failures, QBO token expiry, duplicate detection, missing mappings) with resolution steps
• Escalation Contact Sheet: MSP support email, phone, SLA response times, and emergency procedures

Success Criteria Reviewed with Client:

Credentials and Access Handed Over:

• n8n admin URL and credentials (stored in client's password manager)
• QBO API app credentials (stored in MSP's vault, accessible to client upon request)
• Webhook secret keys (stored in MSP's vault)
• All credentials also documented in MSP's IT documentation platform (IT Glue/Hudu)

Sign-Off:

• Client operations lead signs off on successful parallel run completion
• Client finance lead signs off on invoice accuracy and compliance requirements met
• MSP transitions from project mode to managed service mode with agreed SLA

Maintenance

Ongoing Maintenance Responsibilities

Weekly (MSP Automated):

• n8n Health Check: Automated monitoring via UptimeRobot or equivalent confirms n8n server is responding (HTTPS 200 on /healthz endpoint). Alert threshold: 2 consecutive failures (10 minutes of downtime). Automated restart via Docker Compose watchdog if container crashes.
• Execution Log Review: Automated script checks for failed executions in the past 7 days. Any failures trigger a Slack alert to the MSP team for investigation.

Monthly (MSP Manual — 1–2 hours):

• Execution Log Audit: Review all n8n executions from the past month. Verify zero unresolved errors. Check for any SKIP events that indicate missing project/client mappings that should be added.
• OAuth Token Health: Verify QuickBooks Online and any other OAuth connections are still active. QBO refresh tokens expire after 100 days of inactivity—if the automation has been running regularly, this is not an issue, but verify.
• Disk Space Check: Verify the VM has >20% free disk space. Execution logs and PostgreSQL data can grow. Prune old execution data if needed: n8n Settings > Executions > adjust retention period.
• Billing Reconciliation Support: Provide the client's finance team with the monthly audit log export for reconciliation against QBO records and revenue recognition schedules.

Server Patching: Apply OS security updates to the n8n VM. Update n8n Docker image to the latest stable version (test in staging first if available).

cd /opt/n8n && docker compose pull && docker compose up -d

Quarterly (MSP + Client — 2–3 hours):

• Quarterly Business Review (QBR): Review automation performance metrics: number of invoices auto-generated, error rate, average time from phase completion to invoice creation, any client feedback. Identify optimization opportunities (e.g., new project templates to add, approval workflow adjustments, new integrations).
• Billing Rules Update: Review and update the billing configuration with the client's operations lead. Add any new project templates, update client mappings, adjust billing percentages as needed.
• Security Review: Rotate API keys and webhook secrets. Review n8n user access. Verify SSL certificate auto-renewal is working.
• Compliance Check: For ASC 606 clients, review the audit trail with the client's accountant/CFO to ensure billing events are being properly documented for revenue recognition purposes.

Annual:

• Platform Version Upgrade: Major version upgrades for n8n (test thoroughly before applying). Review PSA and QBO API changelog for breaking changes.
• Disaster Recovery Test: Restore n8n from backup to a test environment and verify all workflows execute correctly. Verify that the PostgreSQL backup contains complete audit trail data.
• Contract and SLA Review: Review the managed service agreement, adjust pricing if scope has changed, and renew.

SLA Considerations:

• Severity 1 (Automation completely down — no invoices being generated): 4-hour response, 8-hour resolution. MSP restarts n8n, checks webhook connectivity, verifies QBO OAuth.
• Severity 2 (Partial failure — some invoices failing, others succeeding): 8-hour response, 24-hour resolution. MSP investigates specific failure pattern (usually a mapping issue or API rate limit).
• Severity 3 (Cosmetic/non-urgent — invoice has wrong description, notification not firing): Next business day response, 3 business day resolution.

Backup Strategy:

• n8n workflow exports: Automated weekly export of all workflows as JSON to the MSP's backup storage (S3/Azure Blob/Google Cloud Storage).
• PostgreSQL database: Daily automated backup via pg_dump, retained for 90 days.
• Configuration files (docker-compose.yml, nginx config): Stored in MSP's Git repository.
• Encryption key and credentials: Stored in MSP's password vault with break-glass access procedures.

Escalation Path:

Alternatives

Native PSA Milestone Billing (No Middleware)

Zapier Team Plan (Fully Managed SaaS Middleware)

Replace self-hosted n8n with Zapier's Team plan as the automation middleware. Zapier offers a fully managed, no-code platform with 7,000+ app connectors, built-in error handling, and a user-friendly interface. The MSP builds and manages Zaps (automation workflows) that connect the PSA to QuickBooks/Xero.

Microsoft Power Automate (Microsoft Ecosystem)

For clients already invested in Microsoft 365 and potentially Dynamics 365, use Power Automate Premium as the automation middleware. Power Automate integrates natively with SharePoint, Teams, Dynamics 365 Project Operations, and can connect to QuickBooks/Xero via premium connectors.

Dynamics 365 Project Operations (Full Enterprise Stack)

Deploy Microsoft Dynamics 365 Project Operations as the end-to-end solution, replacing both the PSA and middleware layers. D365 Project Operations natively supports milestone-based billing with automated invoice scheduling, built-in approval workflows, and direct integration with Dynamics 365 Finance or external ERPs.

Custom Application (Low-Code Platform: Retool or AppSmith)

Build a custom milestone billing dashboard using a low-code platform like Retool or AppSmith that connects directly to the PSA and accounting APIs. This approach gives the client a purpose-built UI for managing billing rules, reviewing pending invoices, and triggering invoice creation—all without the overhead of a full PSA deployment.