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.

The quotes and invoices it makes are the ones on a client's Accounting tab and the Accounting page — see Quotes & invoices.

Key Features:

• 4 Actions: Create quotes/invoices, fetch documents, mark as paid
• Invoice Layout System: Customizable HTML templates with placeholder support
• PDF Generation: Automatic PDF generation, stored with the document
• 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 — for a fixed monthly invoice, see Recurring invoices
• 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; // link to the 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 (rendered and stored in BaseCloud)
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 2a: get_quotes_invoices¶

Find every quote and invoice that matches all the criteria you add, and return their numbers for a Loop — for example, to void or chase each one.

Criteria (add a row for each; one row per kind):

Dates follow the account's timezone. A row left blank is ignored, but a criterion that cannot be used stops the task rather than being dropped — dropping it would widen the search (a Client ID whose variable came out empty would otherwise return every client's documents). With no criteria at all the task stops too. At most 10,000 documents are returned, the most recently added first, and run_text says so when the limit is reached.

Output Variables:

• found: whether anything matched (the task completes either way — branch on this)
• quote_invoice_ids: the numbers, comma-separated — what Fetch, Mark Paid and Void take
• quote_invoice_count, quote_count, invoice_count
• total_amount (tax included) and currency_symbol
• matched_by: the criteria used

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, and its PDF.

One line is made per description; the other lists give each line its code, quantity, cost and tax rate in the same order — keep them the same length, as a value missing from a shorter list leaves that line's field blank. Lines created by this task carry no tracking categories.

Output Variables:

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

How It Works:

1. Checks a client id and an invoice layout are given
2. Splits the pipe-delimited line item lists
3. Takes the next document number (shown as QU…)
4. Sets quote_invoice=0 (indicates quote, not invoice)
5. Sets expiry_date to +7 days from today (hardcoded)
6. Creates invoice record in invoices table
7. Batch inserts line items in invoice_line_items table
8. Triggers Global CRM Automation: Type 3 trigger with var_id='invoice_created'
9. Generates the PDF
10. Returns the document's data, its PDF (document_url) and its payment link (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. Storage: stores the PDF in BaseCloud's file storage under a slugified filename
8. URL Storage: Saves its link in file_url
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¶

Tracking categories (Settings → Tracking Categories) are set on line items in the Accounting page. Documents this task creates have none; Fetch returns those a document's lines carry, as tracking_category_1_label / _value and tracking_category_2_label / _value.

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., QU1024)
• Invoices: INV{invoice_number} (e.g., INV1024)

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. Check the document exists on the Accounting page

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

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

4. Use {{task_22001_quote_invoice_o_id}} from the 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 documents cannot be marked as paid

3. Add conditional check before marking paid:

   If {{task_22001_quote_invoice_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)

Line items come out with blank fields¶

Cause: the pipe-delimited lists have different lengths — each line takes its values by position, and a shorter list leaves the later lines' values blank.

Solution: give every list the same number of values as Item Description(s).

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. Try again — a storage failure is transient

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 a quote or invoice after this task creates it?

A: Not with this task — edit it on the Accounting page.

Q: Can I void a document?

A: Yes — Void Quote / Invoice does what Void on the Accounting page does. A paid document is never voided.

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

A: Quotes (shown as QU…) come before a sale and can be converted to invoices; invoices (INV…) are what gets paid. They share one numbering sequence.

Q: How do I act on many documents — chase every unpaid invoice, void old quotes?

A: Get Quotes / Invoices returns their numbers as quote_invoice_ids; loop over them with a Loop and put Fetch, Mark Paid or Void inside it.

Q: How do I send the invoice?

A: Follow this task with an Email task that attaches {{task_<ID>_document_url}} and includes {{task_<ID>_payment_link}}.

Q: How do I bill clients on a schedule?

A: Start the workflow from a Timer Trigger and create the invoice in it.

Q: What happens when an invoice is paid through its payment link?

A: It is marked paid with today's date, and workflows triggered on invoice paid (a CRM Trigger) run, as they do when it is marked paid by hand or by this task.

Q: Credit notes, partial payments, discounts?

A: Not in this task. A document is paid or unpaid; a discount can be a line with a negative unit cost.

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
• Plaid Trigger - Mark an invoice paid when the payment reaches your bank account

Technical Details¶

• Type ID: 22
• Function: taskBaseCloudAccounting() in automationService.js
• Database Tables: invoices, invoice_line_items, invoice_vars, invoice_layouts, tracking_categories_values
• External Services: Azure Blob Storage (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