deposit-collection

Overview

Deposit Collection is the preventive counterpart to chasing money after the fact: it gets cash in before the work goes out. It creates a deposit request for a configurable share of a job, sends it for payment after one-click owner approval, confirms when the money clears, and records the deposit correctly as a customer prepayment. When the job is done, it generates the final invoice for the remaining balance, netting the deposit already paid.

The accounting matters: a deposit is unearned revenue, a liability the business owes back as work or refund, not income earned. The skill records it against the job and draws it down on the final invoice so the customer is never double-charged and revenue is never overstated.

Workflow

<Definition - Deposit Amount> total_amount times deposit_percentage / 100, rounded to the cent. Example: a $12,000 job at 50 percent is a $6,000 deposit. The percentage defaults to 50 but is owner-configurable per job and often varies by trade (25 for light service, 50 standard, 100 for custom or special-order work the owner must pre-purchase). </Definition - Deposit Amount>

<Definition - Deposit as Liability> Money received before the work is earned is a customer prepayment: a liability the business owes back as either delivered work or a refund. In QuickBooks this is recorded against the customer/job as a deposit or unearned-revenue item, not as income on a normal invoice. It only becomes earned revenue as the work is performed and the final invoice is issued. This is why the final invoice nets the deposit rather than the deposit being booked as a separate sale. </Definition - Deposit as Liability>

<Definition - Final Balance> On job completion: job total plus applicable sales tax minus the deposit already paid. The deposit is applied as a credit/prepayment line on the final invoice so the balance due is only the remainder. If the deposit exceeds the final total (scope shrank), the difference is a credit owed back to the customer, surfaced for the owner to refund or carry. </Definition - Final Balance>

<Workflow - Deposit Collection description="Request a deposit, confirm it cleared, or net it on the final invoice." tools=[recall_memories] triggers=["collect a deposit", "request a deposit", "get a deposit before I start", "invoice a deposit", "bill upfront"]

1. [Agent] Confirm QuickBooks is connected and note which optional connectors (gmail, outlook, paypal) are available. Record the last-sync timestamp. Validate: QuickBooks connected and a sync timestamp returned. If fails: Tell the owner to reconnect QuickBooks in Settings. Stop.

2. [Agent] Look up the customer in QuickBooks by {{customer}}. Capture display name, email, billing address, tax status, and any existing deposit/prepayment already on the job. Validate: Customer found with an email. If fails: Fuzzy-match and present top 3; if none, ask the owner for the customer email so a request can still be sent.

3. [Decide] Which {{stage}} is this run?

   • request: continue to step 4.
   • confirm: go to step 8.
   • final: go to step 9.

4. [Agent] Compute the deposit per <Definition - Deposit Amount> ({{total_amount}} times {{deposit_percentage}}). Read the customer/item tax status; per Rule 5 determine whether the deposit is taxable, and if it is ambiguous, mark it to ask the owner. Validate: Deposit amount computed and reconciles to total times percentage; tax treatment determined or flagged. If fails: Present the math for the owner to confirm.

5. [Ask user] Present the deposit request for approval using <Template - Deposit Request>: customer, job, job total, deposit percentage and amount, tax treatment (or a question if ambiguous), and how it will be sent. Make it one decision. Validate: Owner selects "Send it", "Edit", or "Cancel". If fails: On Edit, adjust and re-present; on Cancel, stop gracefully.

6. [Agent] On approval, create the deposit request in QuickBooks recorded as a customer prepayment / deposit against the job per <Definition - Deposit as Liability> (not as earned income), attaching the shared business payment instruction (recalled from memory under key "business payment instructions for customer invoices", or captured from the owner ONCE and saved there if absent, so no invoicing skill asks again), plus a QuickBooks Payments link only if the connector actually returns one (never fabricated). Apply the tax treatment confirmed in step 5. Validate: Deposit request created, recorded against the job as a prepayment/deposit, with a payment link. If fails: Report the specific error; offer the details for manual entry. Do not book it as a normal income invoice as a workaround.

7. [Agent] Send the request via the available email connector (gmail or outlook), including the payment link (and a PayPal link if PayPal is connected and the customer accepts it). Confirm to the owner what was sent and that you will report when it clears. Validate: Email sent. If fails: Provide the payment link for the owner to share manually. End of the request stage.

8. [Agent] (confirm stage) Check QuickBooks for payment received against the deposit. Honor the staleness check (Rule 9). Report cleared / not yet / partially paid. Only say "safe to start" when the payment is received and has had time to clear. Validate: Payment status read and reported accurately; no false "cleared" on a stale sync or an unpaid request. If fails: Tell the owner the status could not be read and to check QuickBooks. End of the confirm stage.

9. [Agent] (final stage) On job completion, compute the <Definition - Final Balance>: job total plus applicable sales tax minus the deposit already paid. Read the deposit recorded in step 6 and apply it as a credit/prepayment line. Apply the correct tax code (Rule 5). Validate: Final balance reconciles to total plus tax minus deposit; deposit is netted, not ignored or double-counted. If fails: Surface the components for the owner; never bill the full total when a deposit exists.

10. [Ask user] Present the final invoice for approval using <Template - Final Invoice>: job total, tax, deposit applied (as a credit), and balance due. If the deposit exceeds the final total, present the credit owed back for the owner to refund or carry. Validate: Owner approves, edits, or cancels. If fails: On Edit, adjust; on Cancel, stop.

11. [Agent] On approval, create and send the final invoice with the deposit netted and the payment link attached. Validate: Final invoice created with the deposit applied and sent. If fails: Report the error and offer manual details.

</Workflow - Deposit Collection>

<Workflow - Deposit Refund description="Refund or release an unearned deposit when a job is cancelled." tools=[] triggers=["cancel the job", "refund the deposit", "job fell through"]

1. [Agent] Read the deposit recorded against the job and its payment status. Validate: Deposit amount and status retrieved. If fails: Ask the owner for the deposit details.

2. [Think] Per Rule 7, an unearned deposit on a cancelled job is a liability owed back to the customer, subject to the owner's stated cancellation/refund policy (some deposits are partially non-refundable to cover work already done or materials pre-purchased). Determine the refundable amount or ask the owner if the policy is unclear.

3. [Ask user] Present the refund for approval: deposit paid, amount refundable per policy, amount retained (with reason), and how the refund will be issued. Never auto-refund. Validate: Owner approves the refund amount and method, or declines. If fails: Take no action.

4. [Agent] On approval, record the refund in QuickBooks as the return of the prepayment liability (not as a negative sale or an expense), and notify the customer if an email connector is available. Validate: Refund recorded against the prepayment and confirmed to the owner. If fails: Report the error and provide manual steps.

</Workflow - Deposit Refund>

<Template - Deposit Request> Deposit Request Ready to Send:

• To: {{customer}} (customer_email)
• Job: {{job_description}}
• Job total: $X,XXX.XX
• Deposit ({{deposit_percentage}}%): $X,XXX.XX
• Sales tax on deposit: $XX.XX, or "Not taxable", or "Confirm: is this deposit taxable here?"
• Recorded as: customer prepayment (a liability), netted on your final invoice
• Payment: the shared business payment instruction (from memory, or captured once if not yet saved), plus a QuickBooks Payments link only if the connector returns one

<Template - Final Invoice> Final Invoice Ready:

• To: {{customer}} (customer_email)
• Job: {{job_description}}
• Job total: $X,XXX.XX
• Sales tax: $XX.XX (tax code from QuickBooks)
• Deposit already paid: -$X,XXX.XX
• Balance due: $X,XXX.XX
• Due: [date]