BaseCloud Accounting¶

Overview¶

The BaseCloud Accounting task provides integrated accounting functionality within your BaseCloud CRM system. It handles quotes, invoices, PDF generation, payment links, and automated payment tracking—all without requiring external accounting software.

Key Features:

• 4 Actions: Create quotes/invoices, fetch documents, mark as paid
• Invoice Layout System: Customizable HTML templates with placeholder support
• PDF Generation: Automatic document generation with S3 storage
• Payment Links: Integrated payment portal at pay.basecloudglobal.com
• Global Triggers: Fire CRM automations on invoice events
• Tracking Categories: Two-level project/department tracking
• Multi-Currency: Support for multiple currency symbols and formats

Use Cases:

• Automated invoicing workflows triggered by CRM events
• Quote-to-invoice conversion on client approval
• Subscription billing with recurring invoice generation
• Project-based invoicing with tracking categories
• Payment link distribution via email

The layout is an HTML template, not a fixed form. Everything in double braces is replaced when the document is produced, and the right-hand panel lists every placeholder available — click one to insert it. {{line_items}} expands to the whole table rather than a single value.

Prerequisites¶

1. Invoice Layout Configuration¶

Before creating invoices, configure an invoice layout:

1. Navigate to Settings → Quote/Invoice Layout in BaseCloud CRM
2. Create or edit a layout with HTML template
3. Use placeholders like {{invoice_number}}, {{client_name}}, {{total_incl}}, etc.
4. Note the Layout ID (invoice_var_id) for task configuration

2. Client Records¶

• Clients must exist in your CRM with valid client_id
• Client details (name, email, address) populate invoice placeholders

3. Tracking Categories (Optional)¶

• Configure tracking categories for project/department tracking
• Navigate to Settings → Tracking Categories
• Create category values (e.g., Department: Sales, Marketing, Support)

Two categories maximum, because that is Xero's limit — but each can hold any number of options. Categories group invoice line items for reporting and reconciliation, so the names here are what a task writes into when it sets a tracking value.

Outputs¶

A quote or invoice populates the quote_invoice_* group; line-item and tracking fields are filled per item.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: fetch_quote_invoice¶

Retrieve an existing quote or invoice with all details, generate PDF if needed, and create payment link.

Output Variables:

task_22001_client_id; // Client ID associated with invoice
task_22001_id; // Internal invoice database ID
task_22001_invoice_number; // Display number (e.g., 123)
task_22001_o_inv_id; // Full formatted ID ("INV123" or "QU456")
task_22001_type; // "Quote" or "Invoice"
task_22001_status; // "Unpaid", "Void", or "Paid"
task_22001_date_paid; // Date paid (if status=paid)
task_22001_date_created; // Creation date (DD/MM/YYYY HH:mm)
task_22001_date_expiry; // Expiry/due date (DD/MM/YYYY HH:mm)
task_22001_subtotal; // Subtotal before tax
task_22001_total; // Total including tax
task_22001_item_description; // Pipe-delimited descriptions
task_22001_item_code; // Pipe-delimited item codes
task_22001_item_quantity; // Pipe-delimited quantities
task_22001_item_unit_price; // Pipe-delimited unit prices
task_22001_item_tax_rate; // Pipe-delimited tax rates (%)
task_22001_tracking_1_label; // Pipe-delimited TC1 labels
task_22001_tracking_1_value; // Pipe-delimited TC1 value IDs
task_22001_tracking_2_label; // Pipe-delimited TC2 labels
task_22001_tracking_2_value; // Pipe-delimited TC2 value IDs
task_22001_file_name; // Slugified filename for PDF
task_22001_document_url; // S3 URL to generated PDF
task_22001_payment_link; // Payment portal URL

How It Works:

1. Extracts numeric ID from input (removes non-digits: "INV123" → 123)
2. Retrieves invoice from invoices table with all line items
3. Fetches tracking category labels for each line item
4. Generates PDF if not already generated (via Puppeteer + S3 upload)
5. Creates 36-character payment token for payment portal link
6. Returns complete invoice data with pipe-delimited line items

Action 2: paid_quote_invoice¶

Mark an invoice as paid, optionally convert quote to invoice, and trigger global CRM automation.

Output Variables:

Same as fetch_quote_invoice action (returns full invoice data after update).

How It Works:

1. Validates invoice exists and is currently unpaid (status=0)
2. If document is a quote (quote_invoice=0), converts to invoice (quote_invoice=1)
3. Updates status to paid (status=1)
4. Sets date_paid field (defaults to today if not provided)
5. Nullifies file_url to force PDF regeneration with "PAID" stamp
6. Triggers Global CRM Automation: Type 3 trigger with var_id='invoice_paid'
7. Returns complete updated invoice data

Error Scenarios:

• "No quote/invoice found": Invalid document ID provided
• "Invoice already marked as paid": Status is not 0 (unpaid)
• "Invalid Date Paid provided": Date string cannot be parsed

Global Trigger:

When an invoice is marked as paid, BaseCloud automatically runs all CRM automations configured with:

• Trigger Type: Quote/Invoice Changes
• Variable: invoice_paid

This enables automated workflows like:

• Send payment confirmation emails
• Update client status to "Active"
• Trigger fulfillment/provisioning tasks
• Create workflow notes for accounting team

Action 2b: void_quote_invoice¶

Void an unpaid quote or invoice. This does the same as Void on the Accounting page. Nothing is deleted: the document stays on the Accounting page with the status Void.

Output Variables:

• found: whether the document exists
• voided: true when this run voided it
• already_void: true when it was void before this run (nothing changed, no trigger fired)
• client_id, quote_invoice_id, quote_invoice_o_id, quote_invoice_o_id_full, quote_invoice, quote_invoice_status

How It Works:

1. Reads one document number: 1024, INV1024, QU1024, INV-1024 or #1024. Anything else (a list such as 1024,1031, a decimal such as 1024.00) stops the task, rather than joining the digits into a different number. To void many documents, put this task inside a Loop over Get Quotes / Invoices.
2. Looks up the document by its number. No match returns found: false, and the workflow continues. The task stops if two documents share the number, or if the prefix names the wrong kind of document (QU1024 that has since become invoice INV1024).
3. A paid document is never voided. The task stops with the error "INV… is marked as paid, so it was not voided." and the tasks after it do not run. The void is written with status = 0 in the WHERE clause, so a payment that lands while the task runs is also refused.
4. Sets the status to void (status=3) and clears the cached PDF.
5. Triggers Global CRM Automation: Type 3 trigger with var_id='invoice_deleted', only when this run voided the document.

Action 3: create_quote¶

Create a new quote (quote_invoice=0) with line items, tracking categories, and automatic PDF generation.

Output Variables:

Same as fetch_quote_invoice action (returns full quote data after creation).

How It Works:

1. Validates client_id exists in CRM
2. Validates invoice_var_id (layout) exists in invoice_vars table
3. Splits pipe-delimited line item arrays (all must be same length)
4. Generates next sequential o_inv_id (e.g., "QU001")
5. Sets quote_invoice=0 (indicates quote, not invoice)
6. Sets expiry_date to +7 days from today (hardcoded)
7. Creates invoice record in invoices table
8. Batch inserts line items in invoice_line_items table
9. Triggers Global CRM Automation: Type 3 trigger with var_id='invoice_created'
10. Generates PDF document via Puppeteer (HTML template → PDF → S3)
11. Returns complete quote data with PDF URL and payment link

Line Item Calculation:

For each line item:

Subtotal = Quantity × Unit_Cost
Tax_Amount = Subtotal × (Tax_Rate / 100)
Line_Total = Subtotal + Tax_Amount

Invoice totals:

Total_Subtotal = SUM(all line subtotals)
Total_Tax = SUM(all line tax amounts)
Total_Including_Tax = Total_Subtotal + Total_Tax

Action 4: create_invoice¶

Create a new invoice (quote_invoice=1) with line items. Configuration and process identical to create_quote with one difference:

All other fields, validation, and output identical to create_quote action.

Special Features¶

Invoice Layout/Template System¶

BaseCloud uses HTML-based invoice templates with placeholder replacement:

Common Placeholders:

Line Items Loop:

Templates include special section for line item iteration:

<table>
  <tr>
    <th>Description</th>
    <th>Quantity</th>
    <th>Unit Price</th>
    <th>Tax Rate</th>
    <th>Total</th>
  </tr>
  {{#line_items}}
  <tr>
    <td>{{description}}</td>
    <td>{{quantity}}</td>
    <td>{{currency_symbol}}{{unit_price}}</td>
    <td>{{tax_rate}}%</td>
    <td>{{currency_symbol}}{{line_total}}</td>
  </tr>
  {{/line_items}}
</table>

PDF Generation Process¶

1. Template Retrieval: Fetches HTML template from invoice_layouts table
2. Placeholder Replacement: Substitutes all {{...}} placeholders with actual data
3. Puppeteer Rendering:
4. Launches headless Chrome
5. Renders HTML to PDF
6. Settings: A4 size, print background, margins
7. S3 Upload: Uploads PDF to S3 bucket with slugified filename
8. URL Storage: Saves S3 URL in file_url field
9. Special Handling: Detects BaseCloud internal billing (owner_id 10/11) for custom formatting
10. Grouped Line Items: Supports grouping by tracking categories (TC1=76, TC2=77)

PDF Filename Format:

quote-{owner_id}-{invoice_number}-{timestamp}.pdf
// Example: quote-25-123-1705321800000.pdf

Payment Link Generation¶

Payment links enable clients to pay invoices directly via the BaseCloud payment portal:

Link Format:

https://pay.basecloudglobal.com/{token}

Token Generation:

• 36-character alphanumeric token
• Stored in invoices table in payment_token field
• Unique per invoice, never reused

Payment Portal Features:

• Client-facing payment page (BC_PAYMENT_FE)
• Displays invoice details, line items, totals
• Accepts credit card payments
• Automatically marks invoice as paid on successful payment
• Triggers invoice_paid global automation

Global Trigger System¶

BaseCloud fires CRM automations on invoice events:

Trigger Type: Quote/Invoice Changes

Events:

1. invoice_created - Fired when quote or invoice created
2. invoice_paid - Fired when invoice marked as paid
3. invoice_edited - Fired when invoice updated
4. invoice_deleted - Fired when invoice deleted

Usage Example:

Create automation with:

• Trigger: Quote/Invoice Changes
• Variable: invoice_paid
• Tasks: Send receipt email → Update client status → Create workflow note

When any invoice is marked as paid (via task or payment portal), automation runs automatically.

Tracking Categories¶

Track invoices by project, department, cost center, or custom categories:

Configuration:

1. Navigate to Settings → Tracking Categories
2. Create categories (e.g., "Department", "Project")
3. Add category values (e.g., Department: Sales, Marketing, Support)
4. Note value IDs for use in line items

Two-Level Tracking:

• Tracking Category 1: Primary classification (e.g., Department)
• Tracking Category 2: Secondary classification (e.g., Project)

Line Item Assignment:

item_Description: 'Consulting Services|Design Work';
tracking_category_1: '12|13'; // 12=Sales, 13=Marketing
tracking_category_2: '45|45'; // 45=Website Project

Reporting:

Query invoices by tracking categories for departmental/project revenue reports.

Number Management¶

Sequential Generation:

• Quotes and invoices share same sequence per owner
• Function: Get current max invoice_number + 1
• Format: Numeric (e.g., 1, 2, 3, ..., 123)

Full ID Format:

• Quotes: QU{invoice_number} (e.g., QU001)
• Invoices: INV{invoice_number} (e.g., INV001)

Sequence Reset:

Contact BaseCloud support to reset invoice numbering sequence.

Real-World Examples¶

Quote a client when an enquiry arrives¶

Form Submission
  └─ Match to Client            look the client up
      └─ BaseCloud Accounting   create a quote
          └─ Email              send {{task_22001_document_url}}

Turn an accepted quote into an invoice¶

CRM Trigger  (status changed to "Quote accepted")
  └─ BaseCloud Accounting   create the invoice
      └─ Email              send the payment link, {{task_22001_payment_link}}

Chase an unpaid invoice¶

Schedule
  └─ Match to Client            look the client up
      └─ BaseCloud Accounting   fetch the invoice
          └─ If Statement       {{task_22001_quote_invoice_status}} is "Unpaid"
              └─ Email          send the reminder

Troubleshooting¶

Error: "No quote/invoice found"¶

Cause: Invalid document ID provided to fetch_quote_invoice or paid_quote_invoice

Solutions:

1. Verify invoice ID exists in database:

SELECT * FROM invoices WHERE o_inv_id = 'INV123'

1. Check format - accepts "INV123", "QU456", or numeric "123"

2. Ensure invoice belongs to correct owner (multi-tenant system)

3. Use {{task_22001_o_inv_id}} from create action for subsequent fetches

Error: "Invoice already marked as paid"¶

Cause: Attempting to mark invoice as paid when status is not 0 (unpaid)

Solutions:

1. Check current invoice status:

fetch_quote_invoice action → Check {{task_22001_status}}

1. Only mark unpaid invoices (status "Unpaid")

2. Voided invoices (status=2) cannot be marked as paid

3. Add conditional check before marking paid:

   If {{task_22001_status}} equals "Unpaid" → Then mark as paid
   

Error: "Invalid Date Paid provided"¶

Cause: Date string cannot be parsed by JavaScript Date constructor

Solutions:

1. Use standard date formats:
2. DD/MM/YYYY HH:mm ✓
3. YYYY-MM-DD ✓

4. MM/DD/YYYY ✓

5. Leave blank to default to today's date

6. Use Date Formatter task to standardize date format

7. Validate date before passing:

   If {{payment_date}} is not empty → Use {{payment_date}}
   Else → Leave empty (defaults to today)
   

Error: "Client ID not found"¶

Cause: client_id does not exist in clients table

Solutions:

1. Verify client exists in CRM

2. Use valid {{client_id}} from trigger or previous task

3. Create client first with New Client task if needed

4. Check for typos in client ID variable reference

Error: "Invoice Layout ID not found"¶

Cause: invoice_var_id does not exist in invoice_vars table

Solutions:

1. Navigate to Settings → Quote/Invoice Layout in CRM

2. Verify layout exists and note correct ID

3. Ensure layout belongs to current owner (multi-tenant)

4. Use default layout ID if unsure (check with admin)

Error: "Line items length mismatch"¶

Cause: Pipe-delimited arrays have different lengths

Solutions:

1. Count pipe delimiters in each field - must match:

item_Description: "A|B|C"  // 3 items
item_Code: "X|Y|Z"         // 3 items
item_Quantity: "1|2|3"     // 3 items
item_Unit_Cost: "10|20"    // 2 items ✗ MISMATCH

1. Use Formatter task to ensure consistent array lengths

2. Validate data source before creating invoice

3. Use Loop task with individual line item creation if arrays are dynamic

PDF Generation Failed¶

Cause: Puppeteer/Chrome error during PDF rendering

Solutions:

1. Check invoice layout HTML is valid (no unclosed tags)

2. Ensure all placeholders in template have values

3. Verify S3 credentials configured correctly (server-side)

4. Check server has sufficient memory for Puppeteer

5. Retry: Call fetch_quote_invoice again - regenerates PDF

6. Contact BaseCloud support for persistent PDF failures

Payment Link Not Working¶

Cause: Payment token not generated or payment portal misconfigured

Solutions:

1. Verify {{task_22001_payment_link}} is not empty

2. Check payment portal is accessible: https://pay.basecloudglobal.com

3. Ensure invoice belongs to owner with payment portal enabled

4. Regenerate link by calling fetch_quote_invoice again

5. Use payment portal directly with token:

   https://pay.basecloudglobal.com/{{task_22001_payment_token}}
   

Tracking Category Values Not Showing¶

Cause: Invalid tracking category value IDs provided

Solutions:

1. Verify value IDs exist in tracking_categories_values table:

SELECT * FROM tracking_categories_values WHERE id IN (12, 13, 45)

1. Use correct numeric IDs (not labels)

2. Leave blank if no tracking needed (not "null" string)

3. Ensure tracking categories belong to correct owner

Global Trigger Not Firing¶

Cause: No automations configured for invoice_created or invoice_paid event

Solutions:

1. Create automation with Trigger Type: Quote/Invoice Changes

2. Select Variable: invoice_paid or invoice_created

3. Ensure automation is Active (not disabled)

4. Check trigger conditions (if any) are met

5. Verify automation owner matches invoice owner

6. Test by manually marking invoice as paid

Best Practices¶

Invoice Layout Design¶

1. Test Templates: Create test invoice first to preview PDF output

2. Responsive Design: Use tables and fixed widths for consistent PDF rendering

3. Placeholder Validation: Ensure all placeholders have fallback values in template

4. Branding: Include company logo, colors, and contact information

5. Legal Requirements: Include tax registration numbers, terms, and payment instructions

Line Item Management¶

1. Consistent Arrays: Always ensure all pipe-delimited fields have same number of items

2. Item Codes: Use meaningful codes for reporting (e.g., "CONSULT", "DEV", "DESIGN")

3. Descriptions: Be specific - helps clients understand charges

4. Tax Rates: Verify correct tax rates per jurisdiction/product type

5. Tracking: Assign tracking categories for financial reporting

Payment Collection¶

1. Always Include Payment Links: Even if not primary payment method

2. Email Timing: Send invoices during business hours for better engagement

3. Payment Terms: Clearly state due dates and late payment policies

4. Reminders: Set up automated reminders at 7, 14, and 30 days

5. Multiple Channels: Send via email, SMS, and portal notifications

Automation Strategy¶

1. Global Triggers: Leverage invoice_paid and invoice_created for centralized workflows

2. Error Handling: Use If Conditions to handle invoice creation failures gracefully

3. Logging: Always create workflow notes for invoice events (audit trail)

4. Testing: Test automations with quotes first (less impact than invoices)

5. Reconciliation: Regularly compare CRM invoices with accounting records

Security & Compliance¶

1. Access Control: Limit invoice creation to authorized users/automations

2. Data Privacy: Don't include sensitive client data in email bodies (use PDFs)

3. Audit Trail: Use workflow notes to log all invoice actions

4. Backup: Regular database backups include invoice data

5. Tax Compliance: Ensure invoice layouts meet local tax authority requirements

FAQ¶

Q: Can I edit an invoice after it's created?

A: Not directly via task. Invoices are edit-protected once created. Options:

• Void and create new invoice
• Manually edit via database (not recommended)
• Contact BaseCloud support for invoice edits

Q: What's the difference between quotes and invoices?

A:

• Quotes (quote_invoice=0): Pre-sale documents, prefixed "QU", can be converted to invoices
• Invoices (quote_invoice=1): Post-sale documents, prefixed "INV", used for payment collection

Both use same database table and share invoice numbering sequence.

Q: Can I delete or void invoices?

A: Yes, but not via task action:

• Set status=2 in database to void
• Triggers invoice_deleted global automation
• Voided invoices still appear in reports (not deleted)

Q: How do I handle refunds or credit notes?

A: BaseCloud Accounting task doesn't support credit notes. Options:

• Create negative amount invoice (workaround)
• Handle refunds via payment processor directly
• Request credit note feature from BaseCloud support

Q: Can I use custom invoice numbering?

A: Partially:

• invoice_number field is auto-generated sequential
• o_inv_id is formatted as "INV{number}" or "QU{number}"
• Custom numbering requires database changes (contact support)

Q: What currencies are supported?

A: All currencies supported via currency_symbol in invoice layout:

• Set per invoice layout in Settings
• Default: $ (USD)
• Examples: R (ZAR), £ (GBP), € (EUR), ¥ (JPY)

Note: BaseCloud Accounting doesn't handle currency conversion - use single currency per owner.

Q: How do I invoice multiple clients at once?

A: Use Loop task:

1. Google Sheets: get_rows — the list of clients to invoice
2. Loop: Iterate through results
3. Inside Loop: Create Invoice task per client

See Example 3 (Subscription Billing) for complete implementation.

Q: Can I send invoices to multiple recipients?

A: Yes:

• Use Email task with comma-separated addresses
• Or use Loop to send individual emails per recipient
• Payment portal link works for any recipient

Q: What happens if PDF generation fails?

A: Invoice is still created, but file_url is NULL:

• Call fetch_quote_invoice to retry PDF generation
• Check invoice layout HTML for errors
• Contact support if persistent failures

Q: How do I integrate with external payment gateways?

A:

• Use global trigger on invoice_paid event
• Trigger Stripe/Paystack/PayPal webhook task
• Or include payment link in invoice emails
• Payment portal supports credit card processing

Q: Can I schedule invoice generation?

A: Yes, use Timer Trigger:

• Set schedule (e.g., monthly on 1^st at 09:00)
• Add Create Invoice task
• See Example 3 (Subscription Billing)

Q: How do I query invoices for reporting?

A: Read the list from a sheet with Google Sheets:

-- Total revenue this month
SELECT SUM(total) as monthly_revenue
FROM invoices
WHERE status = 1  -- Paid
  AND MONTH(date_paid) = MONTH(CURDATE())
  AND owner_id = {current_owner}

-- Unpaid invoices by client
SELECT c.first_name, c.last_name, i.o_inv_id, i.total
FROM invoices i
JOIN clients c ON i.client_id = c.client_id
WHERE i.status = 0  -- Unpaid
  AND i.quote_invoice = 1  -- Invoice
ORDER BY i.date_created DESC

Q: What's the maximum number of line items per invoice?

A: No hard limit, but practical limits:

• Database limit: 100+ line items supported
• PDF rendering: Very long invoices may have formatting issues
• Recommendation: Group similar items for better readability

Q: How do I add discounts to invoices?

A: BaseCloud Accounting doesn't have dedicated discount field. Workarounds:

1. Discount Line Item: Add negative amount line item
2. Pre-calculate: Subtract discount from unit cost
3. Use Tracking: Mark discount items with specific tracking category

Q: Can I customize email templates for invoice emails?

A: Yes:

• Email task allows full HTML customization
• Use placeholders from task_22001_* variables
• Include PDF attachment: {{task_22001_document_url}}
• Include payment link: {{task_22001_payment_link}}

Q: How do I handle partial payments?

A: BaseCloud Accounting is binary (paid/unpaid). For partial payments:

1. Create workflow note with partial amount
2. Use custom client field to track balance
3. Mark fully paid only when complete
4. Or split invoice into multiple invoices per payment

Q: What happens when invoice is paid via payment portal?

A:

1. Client pays via https://pay.basecloudglobal.com/{token}
2. Payment processed by integrated gateway
3. Invoice status updated to paid (status=1)
4. date_paid set to today
5. Global trigger fires invoice_paid automation
6. Client receives payment confirmation email

Q: Can I use BaseCloud Accounting with external accounting software?

A: Yes, common integrations:

• Export: append invoice data to a sheet with Google Sheets
• Xero/Sage: Create invoices in BaseCloud, sync to external system via API
• QuickBooks: Export CSV and import
• Custom Integration: Use global triggers + Webhook Out tasks

Q: How do I archive old invoices?

A: Invoices never deleted, only voided:

• Query by date range to show recent invoices
• Void old invoices: Set status=2
• Use tracking categories to mark archived periods
• Database retains all historical invoice data

Related Tasks¶

• Email - Send invoice PDFs and payment reminders
• Webhook Out - Integrate with external accounting systems
• Loop - Bulk invoice creation
• If Statement - Handle invoice creation success/failure
• Workflow Note - Log invoice events
• Timer Trigger - Schedule recurring invoicing
• CRM Trigger - Quote/Invoice Changes trigger

Technical Details¶

• Type ID: 22
• Function: taskBaseCloudAccounting() in automationService.js (lines 5029-5650)
• Database Tables: invoices, invoice_line_items, invoice_vars, invoice_layouts, tracking_categories_values
• External Services: AWS S3 (PDF storage), Puppeteer (PDF generation)
• Output Prefix: task_22001_*
• Global Triggers: Type 3 (Quote/Invoice Changes) with var_id values: invoice_created, invoice_paid, invoice_edited, invoice_deleted