Creating an Invoice

Overview

Invoices are how you get paid. When work is complete, you create an invoice that documents what was done and how much is owed. BlueClerk invoices are professional, can accept online payments, integrate with accounting software, and can include photos from your completed work. You can now attach purchase orders to invoices, linking supplier orders to customer billing for complete job cost tracking.

When you create an invoice that doesn't have a linked job or ticket, BlueClerk prompts you to create one - ensuring you maintain complete work records and can schedule follow-up visits if needed.

IMPORTANT: Draft invoices stay DRAFT when saved - When you click "Save" on a DRAFT invoice, it remains as DRAFT and does NOT auto-promote to SENT anymore. This gives you full control over when your invoice becomes visible in accounting software. To mark an invoice as sent, use the "Mark Sent" button in the invoice header after saving.

CRITICAL: Line Item Edits Flush Before Save - When you type a price or quantity into a line item and immediately click Save, BlueClerk now waits for in-flight line item writes to complete before recalculating totals and syncing to QuickBooks. This prevents the "type 300, click Save, it syncs as $0" race condition that caused stale $0 invoices to appear in QuickBooks. The system tracks pending line item mutations using a ref counter and blocks the save operation until all pending writes finish.

NEW: Editable Email Subject Lines - When sending an invoice via email, you can now customize the subject line before sending. The default subject "Invoice [INV-1234] from [Your Company]" can be edited to match your preferred wording or add customer-specific context. This helps your emails stand out in customer inboxes and supports workflows like progress billing where you want to reference specific milestones.

NEW: Email History Panel - Each invoice detail page now shows a complete history of all emails sent for that invoice, including subject line, recipient, send date/time, delivery status (SENT, DELIVERED, BOUNCED, COMPLAINED), and diagnostic codes for failed sends. This helps you track communication with customers and troubleshoot delivery issues without leaving the invoice page.

NEW: Two Delivery Channels - You can now send invoices via email, SMS, or both. The send dialog includes separate checkboxes for "Send by email" and "Send by text". Email shows the recipient email field; SMS shows the phone field. At least one channel must be selected to send. When requesting Approve & Sign, an SMS link goes to the signature page; otherwise it goes to the public invoice view page.

NEW: Email Suppression Check - Before sending an invoice, BlueClerk automatically checks if the recipient email has bounced before or is a placeholder address (.invalid, .test, example.com, placeholder.local). If the email is suppressed, you'll see a clear error message explaining why the send was blocked and prompting you to pick a different address. This prevents bounces from burning your company's email reputation with SES.

NEW: Automatic Item Validation - BlueClerk now validates that every line item's itemId matches the description and price you're writing. This prevents issues like accidentally linking a "Shipping/Freight" service item to a TKO dumbbell line item, which would cause the estimate to display "Shipping/Freight" in the Product/Service column and classify $2,771 of product revenue as freight in QuickBooks. If the item doesn't match, the system returns an error and the AI can self-correct without manual intervention.

NEW: Profit Block (Contractor-Only) - Invoices now show a profit summary block when line items have cost data. See cost subtotal, profit amount, and margin percentage calculated from your catalog's item costs. The block automatically hides if no items have costs, and shows a note when some items are missing cost data. This helps you track job profitability directly from the invoice view.

NEW: Multi-PDF Attachments - You can now attach multiple PDF files to an invoice when sending via email. These attachments appear alongside the invoice PDF in the email, perfect for including supporting documents like job photos, warranty information, or terms and conditions. Upload up to 5 files, each up to 10MB.

NEW: Product Thumbnails - Line items now show thumbnail images for products when available. This helps you visually confirm you're adding the right item, and gives customers a better sense of what they're paying for when reviewing invoices.

NEW: Per-User Email Signature - Email signature settings are now stored at the user level, not the company level. Each team member can configure their own signature in Settings > My Profile, and it will automatically appear at the bottom of invoice and estimate emails they send. This lets your sales team, office manager, and field techs each have their own personalized signature without overwriting each other.

NEW: Automatic Purchase Order Attachment - When you link a purchase order to an invoice, BlueClerk automatically prefills the customer and property from the PO if they're set. This saves time and ensures consistency between what you ordered and what you're billing for.

Creating an Invoice

Starting a New Invoice

1. Click "Finance" in the sidebar
2. Select "New Invoice" from the flyout menu
3. You'll see a blank invoice form

Required Fields

Before you can save an invoice, you need:

• Customer - Who you're billing
• Invoice date - When the invoice was created (defaults to today)
• Due date - When payment is expected (defaults to 30 days from invoice date)
• At least one line item - What you're charging for

Filling Out the Invoice

Selecting a Customer

1. Click the customer field at the top of the form
2. Search for a customer by typing their name
3. Select from the dropdown or create a new customer
4. Property auto-fills if the customer has one property

Adding Line Items

You have two options for adding line items:

Option 1: Manual Entry

1. Click "Add Line Item"
2. Search for an item from your catalog
3. Quantity auto-fills to 1 - adjust if needed
4. Price auto-fills from catalog - adjust if needed
5. Total calculates automatically
6. Click away to save the line item

Option 2: AI Natural Language

1. Find the blue AI bar at the top of the form
2. Type your request in plain English: "2 outlets, 1 panel upgrade, labor $350"
3. Press Enter or click the sparkles button
4. AI matches items from your catalog and prefills line items
5. Review and edit as needed

Setting Invoice Date and Due Date

• Invoice date - Defaults to today, but you can change it
• Due date - Defaults to 30 days after invoice date
• Terms - Set payment terms like "Net 30" or "Due on receipt"

Adding Notes

• Public notes - Visible to customers (thank you message, payment instructions)
• Private notes - Only visible to you (internal notes, job details)

Attaching Files

You can attach up to 5 PDF files to an invoice:

1. Click "Attach Files" in the invoice form
2. Select PDF files from your computer (up to 10MB each)
3. Files upload automatically
4. Remove attachments by clicking the X icon

Attached files are included when you email the invoice to customers.

Linking a Purchase Order

If you've created a purchase order for materials or supplies related to this invoice:

1. Click "Link PO" in the invoice form
2. Search for the purchase order by PO number or supplier name
3. Select the PO from the dropdown
4. Customer and property prefill from the PO if set
5. The PO appears in the invoice's purchase orders section

Sending the Invoice

Customizing the Email Subject

When you click "Send" on an invoice:

1. The send dialog opens
2. Review the default subject line: "Invoice [INV-