Afrexai Invoice Engine

# 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

[PREFIX]-[YEAR].[MONTH].[SEQUENCE]
Example: INV-2026.02.001

╔══════════════════════════════════════════════════════════╗
║  [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]   ║
╚══════════════════════════════════════════════════════════╝

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

DRAFT → SENT → VIEWED → PARTIALLY_PAID → PAID → CLOSED
                  ↓
              OVERDUE → ESCALATED → WRITTEN_OFF
                  ↓
            DISPUTED → RESOLVED → PAID

# 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"

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"

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

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]

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]

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]

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

═══ 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

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"

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."