kiwi-receipts

What this skill does

# Kiwi Receipts

NZ tax assistant for sole trader builders and contractors. Process receipt photos into IRD-ready GST reports, track sales income, calculate annual income tax (IR3), provisional tax, and asset depreciation. Export to XLSX or Xero CSV.

This is a personal-use skill -- each user runs their own instance. No multi-tenant, no login.

## Data Paths

```
~/.openclaw/data/kiwi-receipts/
├── config.json        # Business name, GST number, tax settings
├── receipts.json      # All captured purchase receipts
├── income.json        # Sales/invoice records
├── assets.json        # Depreciable assets register
└── tax-history.json   # Previous years' tax figures (for provisional tax)
```

## First-Time Setup

When user sends "setup", or on first use when `config.json` doesn't exist:

1. Ask for business name
2. Ask for GST/IRD number
3. Ask for vehicle business use % (default 80)
4. Ask for phone business use % (default 70)
5. Save to `~/.openclaw/data/kiwi-receipts/config.json`:

```json
{
  "business_name": "My Construction Ltd",
  "gst_number": "12-345-678",
  "balance_date": "31-march",
  "gst_filing_frequency": "2-monthly",
  "depreciation_method": "DV",
  "vehicle_business_percent": 80,
  "phone_business_percent": 70,
  "home_office_percent": 0
}
```

### income.json structure

Each entry represents an invoice or payment received:

```json
[
  {
    "id": "uuid-here",
    "date": "2026-03-15",
    "client": "ABC Homes Ltd",
    "description": "Bathroom renovation - 42 Rimu St",
    "amount_excl_gst": 8500.65,
    "gst": 1274.35,
    "amount_incl_gst": 9775.00,
    "invoice_number": "INV-2026-015",
    "status": "paid",
    "created_at": "2026-03-15T14:30:00Z"
  }
]
```

### assets.json structure

```json
[
  {
    "id": "uuid-here",
    "name": "DeWalt DCS570 Circular Saw",
    "category": "portable_power_tools",
    "purchase_date": "2026-01-15",
    "cost": 899.00,
    "dv_rate": 0.40,
    "sl_rate": 0.30,
    "method": "DV",
    "business_percent": 100,
    "disposed": false,
    "disposal_date": null,
    "disposal_amount": null,
    "created_at": "2026-01-15T10:00:00Z"
  }
]
```

### tax-history.json structure

```json
{
  "years": {
    "2025": {
      "tax_year_end": "2025-03-31",
      "gross_income": 95000.00,
      "total_expenses": 42000.00,
      "depreciation": 3500.00,
      "taxable_income": 49500.00,
      "tax_on_income": 7582.50,
      "acc_levy": 826.50,
      "total_tax": 8409.00,
      "tax_already_paid": 0,
      "residual_income_tax": 8409.00
    }
  }
}
```

## Handling Receipt Photos

When the user sends an image (check for `MediaPaths` in context):

### Step 1: Analyze the image

Use your vision capabilities to analyze the receipt image. Extract:

```json
{
  "merchant": "Bunnings Warehouse",
  "date": "2026-03-15",
  "items": [
    { "description": "Timber 2x4 3.6m", "quantity": 10, "unit_price": 12.50, "amount": 125.00 },
    { "description": "Concrete Mix 40kg", "quantity": 5, "unit_price": 9.80, "amount": 49.00 }
  ],
  "subtotal": 174.00,
  "gst": 22.57,
  "total": 174.00,
  "gst_number": "123-456-789",
  "payment_method": "EFTPOS",
  "category": "materials"
}
```

**Extraction rules:**
- NZ GST is 15%. If only total is visible, calculate GST as `total × 3/23`
- If GST is shown separately on the receipt, use that value
- Detect the GST number if printed on the receipt
- Classify into categories: `materials`, `tools`, `fuel`, `safety`, `subcontractor`, `office`, `vehicle`, `other`
- Dates: parse to ISO format (YYYY-MM-DD), assume current year if not shown
- All amounts in NZD

### Step 2: Confirm with user

Send back a summary:

```
Receipt captured:
  Merchant: Bunnings Warehouse
  Date: 2026-03-15
  Total: $174.00 (GST: $22.57)
  Items: Timber 2x4 3.6m x10, Concrete Mix 40kg x5
  Category: materials

Reply to save, or correct any details.
```

### Step 3: Save receipt data

After confirmation, append to `~/.openclaw/data/kiwi-receipts/receipts.json`:

```bash
mkdir -p ~/.openclaw/data/kiwi-receipts
```

Read existing `receipts.json` (or start with `[]`), append the new receipt with a generated UUID as `id`, and write back. Each receipt object:

```json
{
  "id": "uuid-here",
  "merchant": "...",
  "date": "2026-03-15",
  "items": [...],
  "subtotal": 174.00,
  "gst": 22.57,
  "total": 174.00,
  "gst_number": "...",
  "category": "materials",
  "payment_method": "EFTPOS",
  "created_at": "2026-03-15T10:30:00Z"
}
```

## Handling Text Commands

### "setup"
Create or update `config.json` with business name and GST number.

### "summary"
Read `receipts.json`, filter to current GST period, show:
```
GST Period: Mar-Apr 2026
Total purchases: $1,527.37
Total GST claimable: $199.13
Receipts: 5

By category:
  Materials: $882.97 (GST: $115.17)
  Tools: $114.00 (GST: $14.87)
  Fuel: $131.40 (GST: $17.14)
  Safety: $399.00 (GST: $51.95)
```

### "report" or "export"
Generate and send XLSX report:

```bash
python3 {baseDir}/scripts/generate_report.py \
  --data ~/.openclaw/data/kiwi-receipts/receipts.json \
  --income ~/.openclaw/data/kiwi-receipts/income.json \
  --assets ~/.openclaw/data/kiwi-receipts/assets.json \
  --tax-history ~/.openclaw/data/kiwi-receipts/tax-history.json \
  --output /tmp/gst-report.xlsx \
  --period current \
  --business-name "from config.json" \
  --gst-number "from config.json"
```

Then send the file back to user via message tool with `sendAttachment` action.

### "report YYYY-MM"
Generate report for a specific GST period (the 2-month period containing that month).

**XLSX report contains up to 7 sheets:**

1. **GST Summary** -- Business info, period, total purchases/GST
2. **All Receipts** -- Date, merchant, category, items, amounts
3. **By Category** -- materials/tools/fuel/safety/etc. subtotals
4. **IRD GST101A** -- Pre-filled with official box numbers (see below)
5. **Income** -- Sales/invoice records (if income.json has data)
6. **Depreciation** -- Asset depreciation schedule (if assets.json has data)
7. **IR3 Annual Tax** -- Annual income tax summary (when period=all or period=annual)

**GST101A auto-fill logic:**

If income.json has data for the period, BOTH sides are auto-filled:
- Box 5: Total sales and income (from income.json) -- AUTO-FILLED
- Box 6: Zero-rated supplies (default $0)
- Box 7: Box 5 - Box 6 -- auto-calculated
- Box 8: Box 7 x 3/23 -- auto-calculated
- Box 9: Adjustments (default $0)
- Box 10: Total GST collected (Box 8 + Box 9) -- auto-calculated
- Box 11: Total purchases incl GST (from receipts.json) -- auto-filled
- Box 12: Box 11 x 3/23 -- auto-calculated
- Box 13: Credit adjustments (default $0)
- Box 14: Total GST credit (Box 12 + Box 13) -- auto-calculated
- Box 15: Box 10 - Box 14 -- FULLY AUTO-CALCULATED

If no income data exists, Box 5 still shows "enter from accounts" as before.

### "delete last"
Remove the most recently added receipt from `receipts.json`.

### "list"
Show recent receipts (last 10) with date, merchant, total.

### "help"
```
Kiwi Receipts -- Commands:

RECEIPTS:
  [Send photo]     Capture a receipt
  "summary"        Current GST period overview
  "report"         Download GST report (XLSX)
  "report 2026-03" Report for specific period
  "list"           Show recent receipts
  "delete last"    Remove last receipt

INCOME:
  "income 9775 description"  Record sales invoice
  "income list"              Show recent income
  "income summary"           Period income total

ASSETS:
  "asset add name $cost"     Register depreciable asset
  "asset list"               Show assets with book values
  "asset dispose name $price" Record asset disposal
  "depreciation"             Calculate this year's depreciation

TAX:
  "provisional"              Calculate provisional tax
  "set last year tax 8409"   Set previous year RIT
  "tax return" / "ir3"       Annual tax summary
  "export ir3"               Annual XLSX report

EXPORT:
  "xero export"              Generate Xero-importable CSV

SETUP:
  "setup"                    Configure business details
  "he