Job To Invoice

Overview

Instant Invoice generates and sends a professional invoice from chat as soon as a job is complete. It pulls customer data and payment terms from QuickBooks, assembles the invoice, requests explicit owner approval, sends it to the customer with payment instructions, and schedules a follow-up reminder. It is built for field service businesses (plumbers, HVAC technicians, landscapers, consultants) that need to invoice promptly after finishing work, without switching between accounting software and email.

Workflow

> Intent guard. A question or status check is NOT an instruction to act. If the > owner is only asking (e.g. "how much would I invoice X for this?", "what's their > email?", "do they have a deposit?"), answer or show a draft summary and STOP - do not > create an invoice in QuickBooks and do not send anything. Creating and sending happen > only after the explicit "Create it" (Step 4) and "Send" (Step 7) approvals. Default > action is do-nothing.

> Data handling safeguard. Do NOT write customer content to the knowledge graph or > long-term memory. Customer records, email addresses, invoice amounts, balances, line > items, and anything pulled from a QuickBooks customer or invoice are read for the > current task only and must never be persisted to the KG or memories. This prevents one > customer's data from leaking into the user's context or a later session. The ONLY value > this skill may store is the business owner's own reusable setting - their payment > instruction (see Step 1) - which is the user's own data, not a customer's. When in > doubt about whether something is the owner's setting or a customer's content, treat it > as customer content and do not store it.

> Source of truth and conflicts. QuickBooks is the source of truth for customer > records, amounts, terms, and tax status; these instructions govern behavior. If a > stored memory conflicts with QuickBooks (for example a payment instruction that no > longer matches), prefer the live QuickBooks data and surface the discrepancy to the > owner rather than guessing. If following an instruction here would require storing > customer content in the KG or memories, the safeguard above wins - do not store it, and > proceed using the data in-task only.

Step 1: Look Up Customer in QuickBooks

• Mode: deterministic
• Tool: quickbooks__QueryEntities
• Params: { "entity": "Customer", "query": "{{customer}}" } - query the Customer entity by the name the user provided
• Output: Customer record including: display name, email address, billing address, default payment terms, and any open quotes/estimates
• Also: recall the business's saved payment instructions via recall_memories (query "business payment instructions for customer invoices" - a SHARED setting any invoicing skill may have saved, not Job-to-Invoice-specific) unless {{payment_link}} was provided; carry it forward for the email pay option in Step 7
• Validate: Customer found with a valid email address on file
• On failure: If no exact match, search with fuzzy matching and present top 3 results for the user to pick. If no results at all, ask the user for the customer's email so the invoice can still be sent.

Step 2: Resolve Line Items and Amount

• Mode: agentic
• Input: {{amount}}, {{service}}, {{quote_ref}}, and the customer record from Step 1
• Output: Structured invoice line items (description, quantity, rate, amount) and total

Logic:

• If {{quote_ref}} is provided, pull line items from that QuickBooks estimate/quote directly - this avoids data re-entry and ensures accuracy.
• If {{amount}} is "per quote", search for the most recent open estimate for this customer and pull from there.
• Otherwise, parse {{service}} and {{amount}} into line items. Handle common patterns:
• Simple: "AC install, $8200" → 1 line item
• Hourly: "40 hours at $150/hr" → qty=40, rate=150, amount=6000
• Multi-line (one customer): "Replaced heater and fixed leak, $450" → multiple line items on ONE invoice

• Compute totals in code, not mentally. Any line-item arithmetic (quantity × rate, "$X each" multiplication, summing line items into a total) MUST be done by generating and running code via run_python. Do not calculate totals in your head. Show the owner the computed figures so they can validate them.

• "Each" vs "total": when the owner says "$X each", multiply per unit/property (e.g. "3 properties at $150 each" = $150 per property, $450 total). When they say "$X total" or just "$X", treat it as the whole. If it is ambiguous which they mean, ask before proceeding - do not assume.
• Batch / multiple recipients: when the request names more than one customer or property ("invoice all three", "bill Elm St, Oak Ave, and Pine Rd"), this produces ONE invoice PER customer/property - not a single combined invoice (unless they explicitly ask for one). First, confirm the resolved list with the owner (names, each amount). Then run the rest of the workflow per invoice: each invoice gets its own create approval (Step 4) and its own email approval (Step 7) - never batch-create or batch-send without per-invoice gates. A single customer with several line items, by contrast, stays as ONE invoice.

• If {{quote_ref}} is provided or {{amount}} is "per quote", reconcile the pulled quote/estimate total against any stated {{amount}}. If they differ, do NOT silently pick one - surface both and ask the owner which is correct before proceeding.
• Amount sanity check (order-of-magnitude): if the resolved total is wildly out of line with this customer's history or the quote (for example 10x the quote, or an apparent extra zero), treat it as likely mis-keyed. HOLD - confirm the amount with the owner before creating or sending. Never create and email an invoice on an unconfirmed outlier amount.

• Validate: Total amount matches the quote (or the owner resolved any mismatch); line items are coherent; no unconfirmed outlier amount.
• On failure: If parsing is ambiguous or the quote and stated amount disagree, present the interpreted line items and both totals and ask the user to confirm before proceeding.

Step 3: Determine Payment Terms

• Mode: deterministic
• Input: {{terms}} (user-provided or default), customer's default terms from QuickBooks
• Output: Final payment terms and due date

Logic:

• If user specified {{terms}}, use that.
• Otherwise use customer's default terms from QuickBooks.
• If neither exists, fall back to net-30.
• Calculate due date from today.

• Validate: Terms are a recognized format (net-15, net-30, net-60, due on receipt)
• On failure: Default to net-30 and note it in the approval summary.

Step 3.5: Apply Sales Tax and Net Any Prior Deposit

• Mode: agentic
• Tool: quickbooks__QueryEntities (read customer tax status and any deposit/credit), then run_python for all arithmetic
• Input: Customer record (Step 1), line items (Step 2)
• Output: Tax-correct line items, the calculation, and the true balance due after any deposit

Do the math in code, never in your head. Any arithmetic in this step (subtotal, tax, deposit netting, balance due) MUST be computed by generating and running code via run_python - do not calculate amounts mentally or inline. After running it, show the owner the calculation it performed (the numbers and the steps: subtotal + tax - deposit = balance due) so they can validate it before approving in Step 4. Money math that the owner cannot check is not acceptable.

Sales tax (ACCT-04A):

• Read the customer's tax status (taxable vs. exempt) and the item/service taxability and tax code from QuickBooks via quickbooks__QueryEntities; apply the correct tax code so QuickBooks calculates tax on the invoice. Sales tax collected is a liability owed to the state, not revenue - invoicing tax-free by default under-collects it.
• If taxability or the jurisdiction's rate is ambiguous (mixed taxable materials and non-taxable labor, multi-jurisdiction, unclear exemption), ASK the owner in the approval step rather than defaulting to no tax. Never invent a tax rate.

Prior deposit (ACCT-04B):

• Check for an open customer deposit, prepayment, retainer, unapplied credit, or a deposit recorded against the related estimate/job. A deposit is unearned revenue (a liability) until the work is done; the final invoice must draw it down.
• If one exists, apply it as a credit/deposit line so the balance due is the net (total + tax - deposit). Do not bill the full amount when a deposit was already collected - that double-charges the customer.

• Validate: Tax code applied (or exemption confirmed); any prior deposit found is netted; the balance due was computed in code and shown to the owner; the balance due reflects total + tax - deposit
• On failure: If tax status cannot be determined, hold for owner confirmation in Step 4. If deposit data is unavailable, note that deposits were not checked and proceed on the gross, flagging it to the owner.

Step 4: Present One-Click Approval

• Mode: agentic
• Input: All resolved data from Steps 1-3
• Output: Approval decision from user

Present a concise invoice summary for approval. This MUST be frictionless - the owner is in the field, possibly on mobile. Use a decision card:

**Invoice ready to create:**
- **To:** {{customer}} (customer_email)
- **For:** {{service description}}
- **Subtotal:** $X,XXX.XX
- **Sales tax:** $XX.XX ({{tax_code}}) - or "Tax-exempt" / "Confirm taxability"
- **Deposit applied:** -$X,XXX.XX (if a prior deposit exists)
- **Balance due:** $X,XXX.XX
- **Due:** [date] (net-30)
- **Payment:** the shared business payment instruction (from memory, or captured once if not yet saved). No QuickBooks/Intuit pay URL is added - the connector returns none, so a generated one would be fabricated.

Create it
Edit
Cancel

If taxability is unknown or ambiguous (from Step 3.5), resolve it HERE before creating - ask "Should this be taxable?" rather than defaulting to no tax. This approval covers the invoice details and creating it in QuickBooks; the outbound email is reviewed separately in Step 7.

• Validate: User selects "Create it"; taxability is confirmed (not silently defaulted); any deposit is reflected in the balance due.
• On failure: If "Edit" - ask what to change, update, and re-present. If "Cancel" - stop workflow gracefully.

Step 5: Create Invoice in QuickBooks

• Mode: deterministic
• Tool: quickbooks__CreateInvoice
• Params: { customer_id, line_items, payment_terms, due_date, tax_code, deposit_credit, memo } - customer ID from Step 1, line items from Step 2, tax code and any deposit credit from Step 3.5, terms and due date from Step 3
• Output: Created invoice with invoice number and PDF link (the connector does not return a customer payment URL, so do not expect or invent one here)

Include:

• Line items from Step 2
• The sales-tax code / taxable status from Step 3.5 so QuickBooks calculates tax (or the confirmed exemption)
• Any prior deposit from Step 3.5 applied as a credit/deposit line so the balance due is net
• Payment terms from Step 3
• Payment link: prefer the shared business payment instruction from memory (key "business payment instructions for customer invoices", saved by any invoicing skill such as Invoice Chaser or Deposit Collection). If none is saved yet, ask the owner ONCE how customers pay (a link or portal, PayPal/Venmo/Zelle/Cash App, bank details, a phone number, or an email) and save it under that shared key so no invoicing skill asks again; substitute the invoice number into any placeholder. Do NOT add a QuickBooks or Intuit pay URL (no intuit.com / connect.intuit.com link): the QuickBooks connector has no get-invoice-share-link action, so any such URL the skill produces is fabricated and invalid. Never fabricate or hand-construct a payment link; if no saved instruction exists and the owner has not provided one, include a payment-contact line and say no online link was included.
• Memo: service description for customer's reference

• Validate: Invoice created successfully with a valid invoice number; tax applied per the confirmed status; deposit netted; no fabricated QuickBooks/Intuit pay URL is included (the connector returns none)
• On failure: If QuickBooks write fails (auth, validation), report the specific error to the user. Suggest they create manually and offer to copy the details to clipboard.

Step 6: Attach Alternative Payment Link (Optional)

• Mode: agentic
• Tool: paypal connector (if connected)
• Input: Invoice amount, customer email
• Output: PayPal.me or PayPal invoice link

Only execute this step if PayPal connector is available. Generate a PayPal payment link as an alternative payment method to include in the email body.

• Validate: Valid PayPal link generated
• On failure: Skip silently - QuickBooks Payments link is sufficient.

Step 7: Present Email Draft for Approval

• Mode: agentic
• Input: The created invoice (number, link, payment URL if any), the assembled email (subject + body), recipient
• Output: Owner approval of the outbound customer email

The invoice exists in QuickBooks now, but nothing has gone to the customer yet. Show the ACTUAL email that will be sent and get explicit approval before sending - approving the invoice in Step 4 is NOT approving the email. This is a customer-facing message and must never send unreviewed.

Every invoice email MUST give the customer a way to pay - never send an invoice with no payment path. Choose the pay option in this order:

1. The current QuickBooks connector does NOT return a customer payment link (it has no get-invoice-share-link action), so do NOT include any QuickBooks or Intuit pay URL - no intuit.com or connect.intuit.com links. Any such link the skill produces is fabricated and invalid; never invent one. Use a tool-provided URL only if a connector tool literally returns one in its result that you can point to.
2. Use the business's saved payment instruction ({{payment_link}} or the value recalled in Step 1) as the pay option - a payment page/link, PayPal.me/Stripe, Venmo/Zelle/Cash App, bank/ACH details, or a check address / pay-by-phone contact.
3. If neither exists (first time, nothing saved), ask the owner ONCE: "How should customers pay you? Paste a payment link or a payment contact and I'll put it on every invoice and remember it across all your invoicing skills." Record the owner's answer as a SHARED business memory so every invoicing skill reuses it, e.g. "Noted: the business's payment instructions for customer invoices are (shared across invoicing skills - Invoice Chaser, Job-to-Invoice, Deposit Collection; do not re-ask)." Do not re-ask once it is saved here or by any sibling invoicing skill.
4. If the owner declines, include a payment-contact fallback ("To arrange payment, reply to this email or call us") and note no link was included.

Never fabricate or hand-construct a payment link. Show the chosen pay option in the draft below.

**Email ready to send to {{customer}} (customer_email):**
Subject: Invoice #[number] from [business name] - [service]

[The full body text as it will appear, including the payment link and due date]

Send + remind
Send only
Edit
Hold

• Validate: Owner picks Send + remind (default) or Send only. If they edit, use their exact wording. The email's pay option is the owner's saved payment instruction or a contact line - confirm it contains NO QuickBooks/Intuit URL (intuit.com / connect.intuit.com) unless a connector tool literally returned one; strip any such fabricated link before sending.
• On failure: If "Edit" - apply the change and re-present. If "Hold" - leave the invoice created in QuickBooks, do not email, and tell the owner they can send it later.

Step 8: Send I

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Amazon-Quick
• Source: Amazon-Quick/Amazon-Quick-official-catalog
• License: MIT-0

Install and usage instructions live in the source repository linked above.