afrexai-invoice-engine

# Invoice Engine — Complete Invoicing & Accounts Receivable

A zero-dependency agent skill for end-to-end invoicing — from quote to payment to reporting.

## Quick Start

When the user says "create an invoice" or "bill [client]":

1. Check if client exists in memory (see Client Registry below)
2. If new client → run Client Onboarding
3. Generate invoice using the Invoice Builder
4. Present for review → finalize
5. Track in the Invoice Ledger

---

## 1. Client Registry

Maintain a YAML client database in your workspace:

```yaml
# clients.yaml
clients:
  - id: "CLI-001"
    name: "Acme Corp"
    contact: "Jane Smith"
    email: "jane@acme.com"
    address:
      line1: "123 Business Ave"
      line2: "Suite 400"
      city: "New York"
      state: "NY"
      zip: "10001"
      country: "US"
    tax_id: "US-EIN-12-3456789"
    payment_terms: "net-30"       # net-15, net-30, net-45, net-60, due-on-receipt, custom
    preferred_currency: "USD"
    default_tax_rate: 0           # 0 for B2B cross-border, local rate for domestic
    notes: "PO required for invoices > $5,000"
    created: "2026-01-15"
    lifetime_revenue: 12500.00
    invoices_sent: 3
    invoices_paid: 2
    avg_days_to_pay: 22
```

### Client Onboarding Checklist
When adding a new client, collect:
- [ ] Legal entity name (exactly as on their records)
- [ ] Billing contact name + email
- [ ] Billing address (full, with country)
- [ ] Tax ID / VAT number (if applicable)
- [ ] Preferred payment terms
- [ ] Currency preference
- [ ] Any PO or approval requirements
- [ ] Tax-exempt? (if so, get certificate reference)

---

## 2. Invoice Builder

### Invoice Number Format
```
[PREFIX]-[YEAR].[MONTH].[SEQUENCE]
Example: INV-2026.02.001
```

Configurable prefix per business line:
- `INV` = standard invoice
- `PRO` = proforma / quote
- `REC` = recurring invoice
- `CN` = credit note

### Invoice Template

When generating an invoice, structure it as:

```
╔══════════════════════════════════════════════════════════╗
║  [YOUR COMPANY NAME]                                     ║
║  [Address Line 1]                                        ║
║  [City, State ZIP]                                       ║
║  [Country]                                               ║
║  Tax ID: [YOUR TAX ID]                                   ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  INVOICE [NUMBER]                  Date: [ISSUE DATE]    ║
║                                    Due:  [DUE DATE]      ║
║                                                          ║
║  Bill To:                          Payment Terms:        ║
║  [CLIENT NAME]                     [Net-30 / etc.]       ║
║  [Client Address]                                        ║
║  [City, State ZIP]                 PO Number:            ║
║  Tax ID: [CLIENT TAX ID]          [If applicable]        ║
║                                                          ║
╠══════════════════════════════════════════════════════════╣
║  #  │ Description          │ Qty │ Rate    │ Amount     ║
╠═════╪══════════════════════╪═════╪═════════╪════════════╣
║  1  │ [Service/Product]    │  1  │ $X,XXX  │ $X,XXX.XX ║
║  2  │ [Service/Product]    │  3  │ $XXX    │ $X,XXX.XX ║
║  3  │ [Expense passthrough]│  1  │ $XXX    │ $XXX.XX   ║
╠═════╧══════════════════════╧═════╧═════════╧════════════╣
║                              Subtotal:    $XX,XXX.XX     ║
║                              Discount:    -$X,XXX.XX     ║
║                              Tax (X%):    $X,XXX.XX      ║
║                              ─────────────────────────   ║
║                              TOTAL DUE:   $XX,XXX.XX     ║
╠══════════════════════════════════════════════════════════╣
║  Payment Methods:                                        ║
║  • Bank Transfer: [Bank] | Acct: [XXXX] | Routing: [XX] ║
║  • PayPal: [email]                                       ║
║  • Stripe: [payment link]                                ║
║  • Bitcoin: [address] / Lightning: [LNURL]               ║
║                                                          ║
║  Notes: [Custom message / thank you / late fee notice]   ║
╚══════════════════════════════════════════════════════════╝
```

### Line Item Types
- **Time-based**: Hours × hourly rate (log hours, auto-calculate)
- **Fixed fee**: Project milestones, retainers
- **Quantity-based**: Units × unit price
- **Expense passthrough**: At-cost or with markup %
- **Discount line**: Negative amount (early payment, volume, loyalty)
- **Recurring**: Auto-populated from recurring schedule

### Tax Handling Decision Tree
```
Is client in same country as you?
├── YES → Apply local tax rate
│   ├── Client tax-exempt? → Add exemption reference, 0% tax
│   └── Client NOT exempt → Apply standard rate
└── NO → Usually 0% (reverse charge / export)
    ├── Both in EU? → Reverse charge mechanism (0%, note on invoice)
    ├── US interstate? → Check nexus rules
    └── International → 0% with export reference
```

### Discount & Pricing Framework
- **Early payment**: 2/10 Net 30 (2% discount if paid within 10 days)
- **Volume**: Tiered pricing (1-10 units = $X, 11-50 = $Y, 51+ = $Z)
- **Loyalty**: After 6+ invoices, offer 5% ongoing discount
- **Bundled**: Package multiple services, discount 10-15% vs à la carte
- **Seasonal**: Q4 premium (+10%), Q1 discount (-5%) if applicable

---

## 3. Invoice Lifecycle & Status Tracking

### Status Flow
```
DRAFT → SENT → VIEWED → PARTIALLY_PAID → PAID → CLOSED
                  ↓
              OVERDUE → ESCALATED → WRITTEN_OFF
                  ↓
            DISPUTED → RESOLVED → PAID
```

### Invoice Ledger (YAML)

```yaml
# invoices.yaml
invoices:
  - number: "INV-2026.02.001"
    client_id: "CLI-001"
    status: "sent"
    issue_date: "2026-02-13"
    due_date: "2026-03-15"
    currency: "USD"
    subtotal: 5000.00
    discount: 0
    tax: 0
    total: 5000.00
    amount_paid: 0
    balance_due: 5000.00
    payment_terms: "net-30"
    line_items:
      - description: "AI Integration Consulting — February"
        qty: 20
        rate: 250.00
        amount: 5000.00
    payments: []
    notes: ""
    sent_date: "2026-02-13"
    reminders_sent: 0
    created: "2026-02-13T10:30:00Z"
```

### Payment Recording
When a payment comes in:
```yaml
payments:
  - date: "2026-03-10"
    amount: 5000.00
    method: "bank_transfer"    # bank_transfer, stripe, paypal, btc, cash, check
    reference: "TXN-ABC123"
    notes: "Paid in full"
```

Update: `amount_paid`, `balance_due`, `status` (→ paid if balance = 0, → partially_paid if balance > 0)

---

## 4. Recurring Invoices

### Schedule Configuration
```yaml
recurring:
  - id: "REC-001"
    client_id: "CLI-001"
    description: "Monthly Retainer — AI Ops Support"
    frequency: "monthly"          # weekly, biweekly, monthly, quarterly, annually
    day_of_month: 1               # 1-28 (avoid 29-31 for safety)
    line_items:
      - description: "AI Operations Retainer"
        qty: 1
        rate: 3500.00
    auto_send: true               # false = create as draft
    start_date: "2026-01-01"
    end_date: null                # null = indefinite
    next_invoice: "2026-03-01"
    invoices_generated: 2
    active: true
```

### Recurring Invoice Routine (run on schedule)
1. Check `recurring` entries where `next_invoice <= today` and `active = true`
2. For each: generate invoice from template, assign next number
3. If `auto_send = true` → mark as sent, notify client
4. If `auto_send = false` → save as draft, notify user for review
5. Update `next_invoice` to next occurrence
6. Log in daily memory

---

## 5. Overdue Management & Collections

### Reminder Schedule
| Days After Due | Action | Tone |
|---|---|---|
| +1 day | Friendly reminder email | "Just a gentle reminder..." |
| +7 days | Follow-up with invoice attached | "Following up on..." |
| +14 days | Firm reminder, mention late fee | "This invoice is now 14 days past due..." |
| +30 days | Final notice before escalation | "Final notice — please remit payment..." |
| +45 days | Escalate to human (Kalin/Christina) | Flag for personal outreach |
| +60 days | Consider write-off or collections | Business decision |

### Reminder Templates

**Day +1 (Friendly)**
```
Subject: Friendly reminder — Invoice [NUMBER] due [DATE]

Hi [CONTACT],

Hope all is well! Just a quick reminder that invoice [NUMBER] for [AMOUNT] was due on [DATE].

If you've already sent payment, please disregard this note.

Payment details are on the attached invoice. Let me know if you need anything.

Best,
[YOUR NAME]
```

**Day +14 (Firm)**
```
Subject: Invoice [NUMBER] — 14 days overdue ([AMOUNT])

Hi [CONTACT],

Invoice [NUMBER] for [AMOUNT] is now 14 days past the due date of [DATE].

Per our agreement, a late fee of [X]% may apply to balances outstanding beyond [Y] days.

Could you confirm when we can expect payment? Happy to discuss if there's an issue.

Thanks,
[YOUR NAME]
```

**Day +30 (Final)**
```
Subject: Final notice — Invoice [NUMBER] overdue ([AMOUNT])

Hi [CONTACT],

This is a final reminder that invoice [NUMBER] for [AMOUNT] remains unpaid, now 30 days past the due date.

Please arrange payment within the next 7 business days to avoid further action.

If there's a dispute or issue with this invoice, please let me know immediately so we can resolve it.

Regards,
[YOUR NAME]
```

### Late Fee Calculation
```
Standard: 1.5% per month on overdue balance (18% APR)
Grace period: 5 business days after due date
Compound: Simple interest (not compound)
Cap: 25% of invoice total (or local legal maximum)

Formula: late_fee = balance_due × (monthly_rate / 30) × days_overdue
Example: $5,000 × (0.015 / 30) × 14 = $35.00
```

---

## 6. Financial Reporting

### Revenue Dashboard (generate weekly/monthly)

```
═══ REVENUE SUMMARY — [MONTH YEAR] ═══

Invoiced This Month:      $XX,XXX.XX  ([N] invoices)
Collected This Month:     $XX,XXX.XX  ([N] payments)
Outstanding (not overdue): $XX,XXX.XX  ([N] invoices)
Overdue:                  $XX,XXX.XX  ([N] invoices, avg [X] days late)
Written Off (YTD):        $XX,XXX.XX

Collection Rate:          XX.X%  (collected / invoiced, trailing 90 days)
Avg Days to Pay:          XX days (trailing 90 days)
Avg Invoice Size:         $X,XXX.XX

═══ TOP CLIENTS (by revenue, YTD) ═══
1. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)
2. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)
3. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)

═══ AGING REPORT ═══
Current (not yet due):     $XX,XXX  ([N] invoices)
1-15 days overdue:         $XX,XXX  ([N] invoices)
16-30 days overdue:        $XX,XXX  ([N] invoices)
31-60 days overdue:        $XX,XXX  ([N] invoices)
60+ days overdue:          $XX,XXX  ([N] invoices) ⚠️

═══ MONTHLY TREND ═══
Jan: $XX,XXX ████████████
Feb: $XX,XXX ████████████████
Mar: $XX,XXX ██████████
...

═══ ACTIONS NEEDED ═══
• [N] invoices need reminder emails
• [N] recurring invoices due for generation
• [Client] has disputed INV-XXXX — needs resolution
```

### Key Metrics to Track
- **Collection Rate**: % of invoiced amount actually collected (target: >95%)
- **DSO (Days Sales Outstanding)**: avg days from invoice to payment (target: <30)
- **Overdue Ratio**: overdue balance / total outstanding (target: <10%)
- **Revenue Concentration**: % from top client (flag if >40% — dependency risk)
- **MRR from Recurring**: recurring invoice total / month

---

## 7. Credit Notes & Adjustments

When a refund or correction is needed:

```yaml
credit_note:
  number: "CN-2026.02.001"
  original_invoice: "INV-2026.01.003"
  client_id: "CLI-001"
  reason: "Partial refund — service hours overcharged"
  line_items:
    - description: "Correction: 5 hours overcharged"
      qty: -5
      rate: 250.00
      amount: -1250.00
  total: -1250.00
  issued: "2026-02-13"
```

Apply credit notes against:
1. The original invoice (reduce balance)
2. Future invoices (credit on account)
3. Direct refund (record refund method + reference)

---

## 8. Multi-Currency Support

```yaml
currencies:
  primary: "USD"
  accepted: ["USD", "GBP", "EUR", "BTC"]
  exchange_rates:  # Update weekly or use live rates
    GBP_USD: 1.27
    EUR_USD: 1.08
    BTC_USD: 97500
  conversion_note: "Converted at rate on invoice date. Payment accepted in invoiced currency only."
```

Rules:
- Always invoice in the client's preferred currency
- Record payments in the currency received
- Convert to primary currency for reporting (use rate on payment date)
- Note exchange rate on invoice if cross-currency
- BTC/Lightning: include both sats and fiat equivalent

---

## 9. Quote-to-Invoice Pipeline

### Quote (Proforma) Template
Same as invoice template but:
- Prefix: `PRO-` instead of `INV-`
- Header: "QUOTATION" instead of "INVOICE"
- Add: "Valid until: [DATE]" (typically 30 days)
- Add: "This is not a tax invoice"

### Pipeline Flow
```
QUOTE → ACCEPTED → INVOICE → PAID
  ↓
EXPIRED (auto-expire after validity period)
  ↓
REVISED (new version with changes)
```

When a quote is accepted:
1. Convert to invoice (change prefix, remove validity notice)
2. Assign invoice number
3. Set payment terms based on client profile
4. Send invoice
5. Archive quote as "converted"

---

## 10. Edge Cases & Rules

### Partial Payments
- Record each payment separately with reference
- Update balance_due after each payment
- On final payment → mark PAID
- If partial + overdue → chase remaining balance only

### Disputed Invoices
- Mark status as DISPUTED
- Record dispute reason and date
- Pause reminders during dispute
- Track resolution (adjusted, credit note, or confirmed correct)
- Resume billing after resolution

### Void vs Credit Note
- **Void**: Invoice was sent in error, never should have existed → mark VOIDED, exclude from reports
- **Credit Note**: Services were delivered but need adjustment → issue CN, include in reports

### Tax Invoice Requirements (by region)
- **US**: No strict format, but include EIN if registered
- **UK/EU**: Must include VAT number, VAT amount, "reverse charge" note if applicable
- **Australia**: Must say "Tax Invoice", include ABN, GST amount
- **Canada**: Include GST/HST number, province-specific rules

### Rounding
- Always round line item amounts to 2 decimal places
- Calculate tax on subtotal (not per-line) to avoid penny discrepancies
- Display currency symbol before amount: $1,234.56

### Invoice Numbering
- NEVER reuse or skip numbers (tax audit requirement)
- Sequential within each prefix
- If voided, keep the number, just mark status

---

## 11. Automation Opportunities

Set up cron jobs or heartbeat checks for:
- [ ] Generate recurring invoices on schedule
- [ ] Send overdue reminders per the schedule above
- [ ] Weekly revenue dashboard to owner
- [ ] Monthly aging report
- [ ] Auto-flag clients with >45 days overdue
- [ ] Quarterly review: update exchange rates, review pricing

---

## 12. Export Formats

When the user needs to export:
- **CSV**: For spreadsheet / accounting import
  ```
  invoice_number,client,date,due_date,total,status,amount_paid,balance
  ```
- **JSON**: For API integration or backup
- **Markdown table**: For quick review in chat
- **PDF-ready text**: Formatted text block ready for PDF generation tool

---

## Commands Reference

| Command | Action |
|---|---|
| "Invoice [client] for [amount/description]" | Create new invoice |
| "Quote [client] for [service]" | Create proforma |
| "Show outstanding invoices" | List unpaid invoices |
| "What's overdue?" | Aging report, overdue only |
| "Revenue this month" | Monthly revenue dashboard |
| "Send reminder for [invoice]" | Generate reminder email |
| "Record payment [invoice] [amount]" | Log payment received |
| "Recurring: [client] [amount] [frequency]" | Set up recurring invoice |
| "Credit note for [invoice]" | Issue credit/adjustment |
| "Client report [name]" | Full client payment history |
| "Export invoices [format]" | CSV/JSON/Markdown export |
| "Void [invoice]" | Void an invoice |
| "Update rates" | Refresh exchange rates |