invoice_runner v1.0.0

name: invoice_runner description: "Run freelance and agency invoicing end to end: issue a clean invoice, set terms that get paid faster, work an aging report, follow a polite-to-firm dunning ladder, and reconcile bank payments against open invoices. Use when someone needs to invoice a client, chase a late payment, build an AR aging or chase list, write a payment reminder, set Net or early-discount terms, or match payments to invoices."

Invoice Runner

Purpose

Take one job from delivered work to paid and reconciled, without dropped invoices, vague follow ups, or payments sitting unmatched. Built for freelancers, small agencies, and the agents who do their admin.

Workflow

1. Set terms before the work starts

Terms agreed after delivery are a negotiation you already lost. Put them in the proposal or agreement:

• Term length: Due on receipt or Net 7 for new or small clients, Net 15 for small B2B, Net 30 for established B2B, Net 45 to 60 only when a larger buyer's pay cycle forces it and the margin survives it.
• Clock start: invoice date, delivery date, or end of month. Name it. Then print a real calendar due date on the invoice, not only the Net shorthand, so the client never has to do date math.
• Deposit: 50 percent upfront is common for project work. New or higher risk clients get payment in advance or a deposit plus shorter terms. Graduate reliable payers to longer terms after a run of on-time payments.
• Early discount, only if margin allows: 2/10 net 30 means a 2 percent discount if paid within 10 days, full amount due in 30. Run bin/invoice_runner.py terms to compute it.
• Late consequence: a late fee or interest clause, a pause on new work, or both. State it up front. Caps and allowed rates vary by place and by contract type, so confirm the figure with the signed agreement and local rules before printing it. Never invent a legal right to a fee the agreement does not grant.

2. Issue the same day you deliver

Delay in sending adds delay in getting paid. The SBA line on this is direct: issue invoices immediately and have a follow up system. Every invoice carries:

• The word Invoice, a unique sequential invoice number, and the invoice date
• Seller name, address, and contact, plus tax ID where the local rules require it
• Buyer legal name, billing contact, and their PO number if they use one
• Itemised lines: what was delivered, dates or period, quantity, unit rate, line total. "Services rendered" alone invites a query, and queries stall payment
• Subtotal, tax rate and tax amount per local rules, any discount, and one bold total due
• Due date in calendar form, accepted payment methods with the exact details or link needed, and the invoice number as the payment reference to quote Check the math and the bill-to name before sending. A wrong name or total bounces the invoice back to the start of the client's queue.

3. Track open invoices weekly

Keep one tracker: invoice number, client, amount, issue date, due date, balance, last contact, promise-to-pay date. Run the aging tool weekly: python3 bin/invoice_runner.py aging --invoices invoices.csv --as-of 2026-11-15 Buckets are current, 1-30, 31-60, 61-90, and 90 plus days past due. Work biggest and oldest first. An invoice with a dispute is not a late payer: flag it disputed, leave the ladder, and resolve the facts first.

4. Run the dunning ladder on schedule

Use the templates in references/dunning-templates.md. The ladder is a system, not a mood:

• Step 0, 3 days before due: courtesy note with total, due date, and pay method
• Step 1, due date: short reminder, ask what they need to release payment
• Step 2, 7 days late: gentle nudge, resend the invoice, ask for a confirmed pay date
• Step 3, 14 to 21 days late: firm email plus a phone call to the billing contact. End every call with a specific promise: amount and date. Log it
• Step 4, 30 to 45 days late: final notice. Name the fee only if the agreement grants it. State the pause on new work if the agreement allows it
• Step 5, 60 to 90 plus days: human decision. Written payment plan, collections, small claims, or write-off. Get local professional advice before a formal step A broken promise escalates one step at once. It is a stronger signal than age alone. Never threaten a step you will not take, and never keep sending step 2 emails for two months.

5. Reconcile every payment against the bank feed

Match three things: the bank deposit, the open invoice, and the remittance detail the payer sent. Run: python3 bin/invoice_runner.py reconcile --invoices invoices.csv --payments payments.csv Matching order:

1. Invoice number quoted in the payment reference, exact amount: paid in full
2. Invoice number quoted, lower amount: partial. Record the remaining balance and ask if the shortfall is a fee, a discount taken, or an error
3. No reference, but one open invoice matches the amount and payer uniquely: propose the match, confirm before closing it
4. One payment covering several invoices: split it across the invoices named in the remittance. If the total is short by a small fixed amount, check for a wire or processor fee before calling it underpaid
5. No match: leave it in an unmatched list with date, payer, and amount. Do not force it onto the nearest invoice Close the loop weekly: open invoices in the tracker must equal unpaid balances, bank deposits marked as invoice payments must each point to an invoice, and partial balances must have a named next step.

6. Fix repeat late payers at the terms, not the inbox

Two late payments in a row changes the next engagement: deposit up front, milestone billing, shorter terms, or pay before delivery. Say it plainly and before work starts. Good payers earn the opposite: longer terms and no deposit.

Output Contract

Deliver one of:

• A ready-to-send invoice draft with every field from step 2 filled, the due date computed, and the terms line spelled out
• A dunning message for the correct ladder step, numbers copied from the invoice record, with the next step and date named
• An aging report with buckets, totals, and a prioritised chase list: invoice, client, amount, days late, next action
• A reconciliation result: matched, partial with remaining balance, unmatched with reason, and still-open invoices Always name the exact next action and its date. Drafts only by default: the human sends invoices and reminders from their own account unless they have clearly authorised sending.

Operating Rules

• Never invent numbers, dates, fees, or legal rights. Every figure comes from the invoice, the agreement, or the tool output. If a late fee is not in the agreement, do not claim one.
• Partial payments, discounts taken late, and overpayments go to a human for a decision. Record them, do not quietly write them off.
• This is admin craft, not legal, tax, or collections advice. Tax treatment, invoice content rules, interest caps, and collection law differ by place. Flag the question and point to a local professional instead of guessing.
• Keep client financial details in the tracker and out of public or shared outputs.
• Money never moves on an agent's say-so. The skill drafts, tracks, and matches. A human approves sending, plan terms, and write-offs.