Invoices Overview

What is an Invoice?

An invoice is a financial document that acts as a bill or formal request for payment from a customer for work that has been completed or services that have been rendered. Invoices are the primary mechanism for converting estimates and change orders into billable revenue.

Key Characteristics

• Billing Document: Formal request for payment with line items and totals
• Source Integration: Generated from estimates and change orders
• Flexible Selection: Choose specific line items or quantities to invoice
• Payment Tracking: Record and track multiple payments against invoices
• Status Management: Draft → Submitted → Paid → Overdue workflow
• Customer Portal: Customers can view, approve, and pay invoices
• Accounts Receivable: Built-in AR tracking and aging reports

Invoice Lifecycle

1. Creation

Invoices can be created through multiple paths:

Manual Creation:

• Create from scratch with custom line items
• Useful for one-off billing or service calls
• Add line items manually with descriptions and amounts

From Estimate:

• Click "Create Invoice" from estimate view
• Automatically includes all estimate line items (initially)
• Can modify selection before finalizing

From Change Order:

• Click "Create Invoice" from change order view
• Includes change order line items
• Maintains reference to source change order

Smart Generation (Agent):

• Say "create an invoice for [job name]"
• Agent automatically includes all uninvoiced items from approved estimates and change orders
• Prevents double-billing by tracking what's already invoiced
• See a future update

From Job View:

• Click "Create Invoice" in job action menu
• Shows all available uninvoiced items
• Select which items to include

2. Line Item Selection

Granular Selection:

• Toggle individual line items on/off for inclusion
• Useful when billing incrementally or for partial completion
• See a future update

Partial Quantities:

• Invoice portion of a line item's total quantity
• Example: Invoice 50 of 100 square feet completed so far
• Track remaining quantity for future invoicing
• See a future update

Line Item Editing:

• Edit descriptions, quantities, and prices on invoice
• Changes on invoice don't affect source estimate/change order
• Maintains reference to source for tracking
• See a future update

3. Invoice Information

Required Fields:

• Customer (pointer to Customer entity)
• Job (pointer to Job entity)
• Line items (at least one)
• Invoice date
• Due date

Optional Fields:

• Invoice number (auto-generated if not provided)
• Description (invoice-level context)
• Internal notes (not visible to customer)
• Customer-facing notes (visible to customer)
• Payment terms (default or custom)
• Late fee configuration
• See a future update and a future update

4. Submission

Submit to Customer:

• Click "Submit Invoice" button
• Changes status from "draft" to "submitted"
• Sends email notification to customer (if configured)
• Makes invoice visible in customer portal

What Happens:

• status field changes to "submitted"
• submittedAt timestamp recorded
• Customer receives email with invoice link
• Invoice appears in customer's account
• AR tracking begins

5. Customer Review

Customer Portal View:

• Customers see submitted invoices in their account
• Can view line items and totals
• Can ask questions or request clarification
• Can approve invoice for payment

Customer Actions:

• View: Review invoice details and line items
• Question: Send message to provider about invoice
• Approve: Confirm invoice is correct and ready for payment
• Pay: Process payment (if payment integration enabled)

6. Payment Recording

Payment Tracking:

• Record payments against invoices
• Multiple payments per invoice supported (for partial payments)
• Track payment method (check, credit card, cash, etc.)
• Payment date and amount recorded

Payment Entity:

• Separate Parse class Payment
• Links to invoice via pointer
• Stores amount, date, method, notes
• Automatically updates invoice status

Invoice Status Updates:

• Paid: Total payments equal or exceed invoice total
• Partially Paid: Some payments recorded but total not reached
• Overdue: Past due date with unpaid balance
• See a future update

7. Overdue Management

Overdue Detection:

• Automatically flagged when due date passes
• Status changes to "overdue"
• Shows days overdue in UI
• Appears in overdue invoice reports

Overdue Actions:

• Send reminder emails (manual or automated)
• Apply late fees (if configured)
• Generate overdue invoice reports
• Escalate collection efforts
• See a future update and a future update

Invoice Components

Line Items

Invoice line items come from two sources:

Estimate Line Items:

• Items from accepted estimates
• Can be included in full or partial quantities
• Reference maintained to source estimate line item
• Prevents double-billing via tracking

Change Order Line Items:

• Items from approved change orders
• Additional work beyond original estimate
• Credit line items (negative amounts) for reductions
• Reference maintained to source change order line item

Invoice-Specific Line Items:

• Added directly to invoice (not from estimate/change order)
• Useful for service calls or unexpected work
• No source reference (standalone items)

Pricing and Totals

Subtotal:

• Sum of all line item totals (quantity × unit price)

Tax (if applicable):

• Applied to taxable line items only
• Calculated based on job location tax rate
• Some items may be tax-exempt

Total:

• Subtotal + Tax
• This is the amount customer owes

Amount Paid:

• Sum of all payment amounts recorded
• Updated automatically when payments recorded

Balance Due:

• Total - Amount Paid
• Amount customer still owes

Source Tracking

Estimate Reference:

• sourceEstimate pointer field
• Links invoice line items to estimate line items
• Enables "what's been invoiced" reporting
• Prevents double-billing

Change Order Reference:

• sourceChangeOrder pointer field
• Links invoice line items to change order line items
• Tracks change order invoicing
• Prevents double-billing

Invoiced Status:

• Estimate and change order line items track if they've been invoiced
• invoiced boolean field (future enhancement)
• Enables smart invoice generation
• See a future update

Invoice Status

Invoices have a status field indicating their current state:

• draft: Invoice created but not submitted to customer
• submitted: Sent to customer, awaiting payment
• paid: Fully paid (payments equal or exceed total)
• partially_paid: Some payments received but balance remains
• overdue: Past due date with unpaid balance
• void: Invoice cancelled/voided (not valid)

Accounts Receivable (AR)

AR Tracking

What is AR?:

• Accounts Receivable = money owed by customers
• Outstanding invoice balances
• Critical for cash flow management

AR Dashboard:

• Total AR amount across all customers
• Breakdown by customer
• Aging report (current, 30, 60, 90+ days)
• Overdue invoice list
• See a future update

AR Aging:

• Current: Invoices not yet due
• 1-30 days: Past due up to 30 days
• 31-60 days: Past due 31-60 days
• 61-90 days: Past due 61-90 days
• 90+ days: Past due over 90 days

AR Reporting

Available Reports:

• Total AR by customer
• Aging summary (how old are outstanding invoices)
• Overdue invoice list
• Payment collection forecasts
• Cash flow projections
• See a future update

Report Formats:

• Dashboard widgets
• Exportable PDF reports
• Excel/CSV export for accounting software
• Scheduled email reports

Agent Capabilities

The Invoice Agent can help with various invoice-related tasks using natural language commands:

Creating Invoices

Commands:

• "Create an invoice for [job name]"
• "Bill [customer name] for [job name]"
• "Generate an invoice for the work we completed"
• "Invoice [customer] for [amount]"

Smart Generation:

• Agent automatically identifies uninvoiced items from estimates and change orders
• Includes all approved, uninvoiced line items
• Prevents double-billing
• Asks for confirmation before creating
• See a future update

Searching Invoices

Commands:

• "Find invoices for [customer name]"
• "Show me unpaid invoices"
• "List overdue invoices"
• "Find invoices from last month"
• "Show invoices over $5000"

Search Capabilities:

• Search by customer name
• Filter by status (draft, submitted, paid, overdue)
• Filter by date range
• Filter by amount range
• Filter by job
• Returns formatted list with invoice details

Invoice Information

Commands:

• "What invoices are overdue?"
• "How much does [customer] owe?"
• "Show me my total accounts receivable"
• "What invoices are due this week?"
• "Tell me about invoice #12345"

Information Provided:

• Invoice status and details
• Payment history
• Outstanding balance
• Due date and days overdue
• Source estimate/change order references
• Customer information

Updating Invoices

Commands:

• "Submit invoice #12345 to the customer"
• "Mark invoice #12345 as paid"
• "Add a $500 payment to invoice for [customer]"
• "Void invoice #12345"

Supported Updates:

• Submit invoices to customers
• Record payments
• Void/cancel invoices
• Update due dates
• Add notes

Generating Reports

Commands:

• "Show me my accounts receivable aging report"
• "Generate an overdue invoice report"
• "What's my total AR?"
• "Show me payment trends this month"

Report Types:

• AR aging summary
• Overdue invoices
• Payment collection summary
• Cash flow forecasts
• See a future update

Financial Tracking

Revenue Recognition

When Revenue is Recognized:

• Revenue recognized when invoice is paid (cash basis)
• Or when invoice is submitted (accrual basis, configurable)
• Affects financial reports and tax reporting

Tracking:

• Total revenue by period (month, quarter, year)
• Revenue by customer
• Revenue by job type
• Revenue trends and forecasts

Cost Tracking

Job Costs:

• Track actual costs against invoiced amounts
• Calculate profit margins per job
• Identify profitable vs. unprofitable work

Profitability:

• Invoice Total - Job Costs = Profit
• Profit margin percentage
• Break down by job, customer, or service type

Customer Portal

Invoice Visibility

What Customers See:

• All submitted invoices for their account
• Invoice line items and descriptions
• Payment history
• Outstanding balance
• Due dates
• Downloadable PDF invoices

Customer Actions:

• View invoice details
• Ask questions about invoices
• Approve invoices
• Make online payments (if enabled)
• Download invoice PDFs
• View payment history

Payment Terms and Late Fees

Payment Terms

Default Terms:

• Net 30 (due in 30 days)
• Net 15 (due in 15 days)
• Due on receipt (immediate payment)
• Custom terms (configurable per invoice)
• See a future update

Terms Include:

• Payment due date
• Accepted payment methods
• Late fee policy
• Discount for early payment (optional)

Late Fees

Late Fee Configuration:

• Percentage of balance (e.g., 1.5% per month)
• Flat fee (e.g., $25 late fee)
• Applied automatically or manually
• Grace period before applying fee
• See a future update

Late Fee Application:

• Automatically applied after grace period
• Shows as separate line item on invoice
• Customer notified when late fee applied
• Late fees can be waived manually

Integration Points

Estimates

From Estimate to Invoice:

• Create invoice from accepted estimate
• Include all or some estimate line items
• Maintain reference to source estimate
• Track what's been invoiced vs. not invoiced

Uninvoiced Items:

• View which estimate line items haven't been invoiced yet
• Prevents double-billing
• Smart invoice generation includes uninvoiced items
• See a future update

Change Orders

From Change Order to Invoice:

• Create invoice from approved change order
• Include all or some change order line items
• Maintain reference to source change order
• Track change order invoicing

Credit Change Orders:

• Change orders can have credit line items (negative amounts)
• Credits appear as negative amounts on invoice
• Reduces total invoice amount
• Useful for scope reductions or customer credits

Jobs

Job-Invoice Relationship:

• Each invoice tied to a specific job
• View all invoices for a job
• Track job revenue vs. costs
• Job profitability reporting

Job Status Updates:

• Jobs can track invoice status
• "Awaiting payment" status when invoice submitted
• "Paid" status when all invoices paid
• Affects job completion tracking

Payments

Payment Recording:

• Create Payment entities linked to invoices
• Record payment date, amount, method
• Partial payments supported
• Payment history visible to customer

Payment Methods:

• Check (record check number)
• Credit card (record last 4 digits)
• Cash
• ACH/bank transfer
• Online payment (if integrated)
• Other (custom)

Common Workflows

Workflow 1: Standard Invoicing

1. Complete Work: Finish work described in estimate
2. Create Invoice: Generate invoice from estimate
3. Review Line Items: Verify all items are correct
4. Submit to Customer: Send invoice to customer
5. Customer Reviews: Customer views invoice in portal
6. Customer Approves: Customer confirms invoice is correct
7. Record Payment: Customer pays, provider records payment
8. Invoice Marked Paid: Status updates to "paid"

Workflow 2: Incremental Invoicing

1. Partial Completion: Complete portion of work
2. Create Invoice: Generate invoice for completed work
3. Select Partial Quantities: Invoice 50 of 100 units completed
4. Submit to Customer: Send invoice for partial work
5. Record Payment: Customer pays partial invoice
6. Continue Work: Complete remaining work
7. Create Second Invoice: Invoice remaining quantities
8. Submit and Collect: Send second invoice and collect payment

Workflow 3: Change Order Invoicing

1. Change Order Approved: Customer approves change order
2. Complete Change Order Work: Finish additional work
3. Create Invoice: Generate invoice from change order
4. Include Original Estimate (optional): Combine with uninvoiced estimate items
5. Submit to Customer: Send combined invoice
6. Record Payment: Collect payment for all work

Workflow 4: Overdue Collection

1. Invoice Overdue: Due date passes without payment
2. Automatic Reminder: System sends reminder email
3. Follow-Up Call: Provider calls customer
4. Late Fee Applied: Late fee added after grace period (if configured)
5. Payment Received: Customer pays with late fee
6. Invoice Marked Paid: Status updates to "paid"

Workflow 5: Smart Invoice Generation (Agent)

1. Say Command: "Create an invoice for [job name]"
2. Agent Analyzes: Reviews estimate and change orders
3. Agent Identifies Uninvoiced Items: Finds all items not yet invoiced
4. Agent Proposes Invoice: "I can create an invoice with [list of items]"
5. Confirm: "Yes, create that invoice"
6. Invoice Created: Agent creates invoice with all uninvoiced items
7. Review and Submit: Provider reviews and submits to customer

• See a future update

FAQs

Invoice Creation

Q: How do I create an invoice? A: You can create invoices in several ways:

1. From an estimate: Click "Create Invoice" on estimate view
2. From a change order: Click "Create Invoice" on change order view
3. From job view: Use "Create Invoice" action in job menu
4. Ask the agent: "Create an invoice for [job name]"
5. Manual creation: Click "New Invoice" and add line items manually

Q: Can I invoice only part of an estimate? A: Yes! When creating an invoice from an estimate, you can toggle individual line items on or off. You can also invoice partial quantities of line items (e.g., 50 of 100 units). This allows for incremental billing as work progresses. See a future update and a future update

Q: What happens if I edit a line item on an invoice? A: Changes to line items on an invoice (description, quantity, price) only affect the invoice, not the source estimate or change order. The invoice maintains a reference to the source for tracking purposes, but the two are independent. See a future update

Q: Can I combine estimate and change order items on one invoice? A: Yes! You can create an invoice that includes line items from both the original estimate and any approved change orders. The smart invoice generation feature does this automatically. See a future update

Q: How do I prevent double-billing a customer? A: The system tracks which line items from estimates and change orders have been invoiced. The smart invoice generation feature automatically excludes already-invoiced items. You can also manually review what's been invoiced before creating a new invoice. See a future update

Line Items and Pricing

Q: Can I add line items directly to an invoice without an estimate? A: Yes! You can add custom line items directly to an invoice. This is useful for service calls, unexpected work, or one-off charges. These line items won't have a source estimate or change order reference.

Q: How do partial quantity invoices work? A: If an estimate line item has 100 units, you can create an invoice for 50 units now and 50 units later. The system tracks how much has been invoiced and how much remains. This is useful for progress billing. See a future update

Q: Can I invoice for more than the estimate amount? A: Yes, but it's recommended to use change orders for additional work. If you need to invoice more than estimated, you can add line items directly to the invoice or create a change order first.

Q: How are taxes calculated on invoices? A: Taxes are calculated based on the job location's tax rate. Each line item can be marked as taxable or non-taxable. The invoice shows subtotal, tax, and total.

Q: Can I apply discounts to invoices? A: Yes! You can add a discount line item with a negative amount, or adjust individual line item prices. Discounts reduce the invoice total.

Invoice Submission

Q: What happens when I submit an invoice? A: When you submit an invoice:

1. Status changes from "draft" to "submitted"
2. Customer receives email notification (if configured)
3. Invoice becomes visible in customer portal
4. AR tracking begins
5. Due date countdown starts

Q: Can I edit an invoice after submitting it? A: Generally, no. Once submitted, invoices should not be edited to maintain financial integrity. If changes are needed, void the invoice and create a new one. Some fields like internal notes may be editable.

Q: How do I send an invoice to a customer? A: Click "Submit Invoice" button. The system sends an email with a link to view the invoice in the customer portal. Customers can also see submitted invoices when they log into their account.

Q: Can I un-submit an invoice? A: No, submitted invoices cannot be un-submitted. If you need to cancel an invoice, void it and create a new one.

Payment Tracking

Q: How do I record a payment? A: From the invoice view, click "Record Payment". Enter the payment amount, date, method (check, card, cash), and any notes. The invoice status updates automatically based on payments received.

Q: Can I record partial payments? A: Yes! You can record multiple payments against an invoice. For example, record a $500 payment today and another $500 payment next week. The invoice status shows "partially_paid" until the full amount is received.

Q: What payment methods can I track? A: You can track:

• Check (with check number)
• Credit card (last 4 digits)
• Cash
• ACH/bank transfer
• Online payment
• Other (custom)

Q: How do I know if an invoice is fully paid? A: The invoice status changes to "paid" when total payments equal or exceed the invoice total. The "Balance Due" field shows $0.00.

Q: What if a customer overpays? A: You can record the overpayment amount. The balance due will show a negative amount (credit). You can apply this credit to a future invoice or issue a refund.

Overdue Invoices

Q: When does an invoice become overdue? A: An invoice becomes overdue the day after the due date passes if there's still an unpaid balance. The status changes to "overdue" and the invoice appears in overdue reports. See a future update

Q: How do I find overdue invoices? A: You can:

1. View the overdue invoices dashboard widget
2. Ask the agent: "Show me overdue invoices"
3. Filter invoices by status = "overdue"
4. Run an AR aging report See a future update

Q: Can I send reminder emails for overdue invoices? A: Yes! You can manually send reminder emails from the invoice view. Automated reminder emails can also be configured (future enhancement). See a future update

Q: How do late fees work? A: Late fees can be configured per invoice or use default settings. After a grace period (e.g., 7 days past due), a late fee is automatically or manually applied. Late fees appear as separate line items on the invoice. See a future update

Q: Can I waive a late fee? A: Yes! Late fees can be waived or removed manually. This is useful for good customers or special circumstances.

Accounts Receivable

Q: What is accounts receivable (AR)? A: Accounts receivable is the total amount of money customers owe you from unpaid invoices. It's a critical metric for cash flow management.

Q: How do I see my total AR? A: You can:

1. View the AR dashboard widget
2. Ask the agent: "What's my total accounts receivable?"
3. Run an AR summary report See a future update

Q: What is an AR aging report? A: An AR aging report shows how old your outstanding invoices are, grouped into buckets (current, 1-30 days, 31-60 days, etc.). This helps identify collection priorities and cash flow risks. See a future update

Q: How do I improve my AR collection? A: Best practices:

1. Send invoices promptly after work completion
2. Follow up on overdue invoices quickly
3. Offer multiple payment methods
4. Consider early payment discounts
5. Apply late fees for chronic late payers
6. Use AR aging reports to prioritize collection efforts

Q: Can I export AR reports to my accounting software? A: Yes! AR reports can be exported as PDF, Excel, or CSV for import into QuickBooks, Xero, or other accounting systems. See a future update

Invoice Status

Q: What do the different invoice statuses mean? A:

• draft: Invoice created but not sent to customer yet
• submitted: Sent to customer, awaiting payment
• paid: Fully paid (no balance due)
• partially_paid: Some payments received, balance remains
• overdue: Past due date with unpaid balance
• void: Cancelled/voided (not valid)

Q: How do I void an invoice? A: From the invoice view, click "Void Invoice" (or ask the agent: "Void invoice #12345"). Voided invoices are marked as invalid and removed from AR. If the customer already paid, you'll need to issue a refund separately.

Q: Can I change an invoice's due date? A: Yes, but only before submitting. Once submitted, changing the due date is not recommended as it affects AR tracking. If necessary, void and recreate the invoice with the correct due date.

Agent Commands

Q: Can I create an invoice by talking to the agent? A: Yes! Say "Create an invoice for [job name]" or "Bill [customer name] for [job name]". The agent will generate an invoice with all uninvoiced items from the estimate and change orders. See a future update

Q: How does the agent know what to include in an invoice? A: The agent analyzes the job's estimate and change orders, identifies line items that haven't been invoiced yet, and proposes including them. It prevents double-billing by tracking what's already been invoiced. See a future update

Q: Can I ask the agent about invoice status? A: Yes! Try:

• "What invoices are overdue?"
• "How much does [customer] owe?"
• "Show me my accounts receivable"
• "Tell me about invoice #12345"

Q: Can the agent record payments? A: Yes! Say "Record a $500 payment for invoice #12345" or "Mark invoice for [customer] as paid". The agent will update the invoice status accordingly.

Customer Portal

Q: What do customers see in their portal? A: Customers see:

• All submitted invoices for their account
• Invoice line items and totals
• Payment history
• Outstanding balance
• Downloadable PDF invoices
• Due dates and overdue status

Q: Can customers pay invoices online? A: If payment integration is enabled (Stripe, Square, etc.), customers can pay invoices directly in the portal. Otherwise, they need to pay by check, cash, or other offline methods.

Q: Can customers dispute or question invoices? A: Yes! Customers can send messages about invoices through the portal. These messages appear in your inbox and can be addressed through conversation.

Integration

Q: Can I import invoices from another system? A: Invoice import is not currently supported, but can be added as a feature. Contact support if you need to migrate invoices from another system.

Q: Can I export invoices to QuickBooks or other accounting software? A: Yes! Invoices and payments can be exported as CSV or via accounting software integrations. See documentation for specific integration steps.

Q: Does HomeGuild integrate with payment processors? A: Payment integrations (Stripe, Square, PayPal) can be configured to enable online customer payments. Contact support for setup assistance.

Invoice Notes and Terms

Q: Can I add notes to an invoice? A: Yes! You can add:

• Invoice description: High-level context about the invoice (visible to customer)
• Internal notes: Notes for your team (not visible to customer)
• Customer-facing notes: Additional information for customer (visible in portal) See a future update

Q: Can I customize payment terms per invoice? A: Yes! You can set custom payment terms for each invoice, or use your default terms (Net 30, Net 15, etc.). Terms include payment due date, accepted methods, and late fee policy. See a future update

Q: Can I add terms and conditions to invoices? A: Yes! You can define standard terms and conditions that appear on invoices (payment terms, warranties, liabilities, etc.). These can be customized per invoice if needed. See a future update

Related Features

• Estimates: Create project estimates with line items and pricing
• Change Orders: Document scope and price changes to jobs
• Jobs: Track work projects from lead to completion
• Customers: Manage customer information and relationships
• Line Items: Standardized pricing components
• Payments: Record and track customer payments

Related Issues

• a future update: Granular Invoice Item Selection from Estimates and Change Orders
• a future update: Partial Quantity Invoicing for Line Items
• a future update: Invoice Line Item Editing Impact on Source Tracking
• a future update: Overdue Invoice Tracking and Notifications
• a future update: Enhanced Accounts Receivable Reporting and Analytics
• a future update: Late Fees for Overdue Invoices
• a future update: Smart Invoice Generation via Agent
• a future update: Invoice-Level Description and Notes
• a future update: Customizable Payment Terms and Conditions

Additional Resources

• Billing Best Practices
• Cash Flow Management
• Agent Command Reference