il-invoice-organizer

name: il-invoice-organizer description: "Parse and organize Hebrew invoices for Israeli bookkeeping: VAT 1/6 extraction, Tax Authority expense categories, Osek Murshe/Patur recognition, and accountant-ready export. Use when user asks about organizing invoices, cheshbonit, expense categorization, sivug hotza'ot, VAT extraction from totals, Osek Murshe vs Osek Patur rules, or preparing documents for their accountant (ro'eh cheshbon). Supports Hebrew OCR text parsing and automatic categorization per Tax Authority standards. Do NOT use for invoice generation (use israeli-e-invoice instead) or for VAT report filing (use israeli-vat-reporting instead)." license: MIT compatibility: "Works with Claude Code, Cursor, GitHub Copilot, Windsurf, OpenCode, Codex. Python 3.8+ for helper scripts."

IL Invoice Organizer

Instructions

Step 1: Identify Invoice Type and Source

Determine what documents the user has:

Key: Only tax invoices (300, 305) allow VAT input deduction (nikui mas tsumos).

Step 2: Extract Invoice Data

Parse the following fields from each invoice:

SHAAM allocation threshold timeline (Israel Tax Authority, accelerated rollout):

A B2B tax invoice above the threshold without a valid SHAAM allocation number (מספר הקצאה) is not eligible for VAT input deduction. Always check the threshold for the invoice issue date, not today's date.

Step 3: Extract VAT (1/6 Rule)

Israeli VAT is 18% (raised from 17% effective 1 January 2025). For invoices where only the total (gross) is visible:

# VAT extraction from gross amount (כלל השישית)
vat_rate = 0.18  # 18% standard rate (effective 1 Jan 2025)
gross_amount = 1180  # סכום כולל מע"מ

# Method: VAT = gross * (rate / (1 + rate)) = gross * (18/118)
vat_amount = gross_amount * (vat_rate / (1 + vat_rate))
# = 1180 * (0.18 / 1.18) = 1180 * 0.1525... = 180.00

net_amount = gross_amount - vat_amount
# = 1180 - 180 = 1000

Shortcut at 18%: VAT ≈ Total / 6.556 (the divisor is 118/18). The colloquial name "klal hashishit" (the 1/6 rule) predates the rate hike and is now an approximation, not a literal sixth.

Step 4: Categorize by Tax Authority Standards

Assign each expense to a Tax Authority category. Codes 1–12 align with references/expense-categories.md and the keyword-based auto-categorizer in scripts/categorize_invoices.py:

Use scripts/categorize_invoices.py for automatic categorization.

Step 5: Identify Business Type

Determine supplier and customer business status:

Important: You can only deduct input VAT (mas tsumos) from tax invoices issued by Osek Murshe (or Hevra Peratit) suppliers. Receipts from Osek Patur do not have VAT to deduct.

Osek Patur turnover ceiling (2026): NIS 122,833 (raised from NIS 120,000 in 2024–2025). Once a freelancer crosses this annual turnover, they must convert to Osek Murshe from the date of the breach and notify the VAT office. Certain professions (lawyers, doctors, architects, engineers, accountants and a few others) are barred from Osek Patur status regardless of turnover.

Invoice issuance timing: Israeli tax law requires a tax invoice (Heshbonit Mas) to be issued within 14 days of the taxable supply or of payment, whichever comes first. Invoices dated more than 14 days after the supply may be challenged by the Tax Authority.

Step 6: Generate Accountant-Ready Export

Organize the data for the accountant (ro'eh cheshbon).

Output format (CSV/Excel):

Date, Supplier, TIN, Invoice#, Category, Net, VAT, Total, Notes
15/01/2026, חברת אלפא, 515000000, 1234, קבלני משנה, 10000, 1800, 11800, שירותי פיתוח

Include summary:

• Total expenses by category
• Total input VAT (mas tsumos) to reclaim
• Missing invoices or data gaps flagged
• Separate section for non-deductible items

Step 7: Align with Filing Deadlines

Surface the relevant filing windows so the user knows when the accountant needs the organized batch.

Hand the categorized batch to the accountant at least 7-10 days before the VAT deadline so they have time to reconcile and file. For invoices over the SHAAM threshold without an allocation number, flag urgently: the deadline to request a corrected invoice from the supplier is before that period's VAT filing.

Osek Zair (Small Dealer) option: a self-employed individual with annual revenue ≤ NIS 122,833 may elect the "Small Dealer" track on the annual return and deduct a flat 30% of revenue as expenses instead of actual expenses. The election is not available if the freelancer has employees, has inadequate books, more than 25% of revenue is from a related party, the freelancer is a 10%+ shareholder in a company, or other Finance Minister exclusions apply. When this election is in play, this skill should still organize invoices for backup and Bituach Leumi purposes, but the categorized totals will not flow to the income tax return.

Examples

Example 1: Monthly Invoice Organization

User says: "I have 30 invoices from this month. Help me organize them for my accountant" Actions:

1. Collect: Invoice images or text data from user
2. Parse: Extract supplier, amount, VAT, date from each
3. Categorize: Assign Tax Authority category per Step 4
4. Validate: Check TIN format, VAT calculation, allocation numbers
5. Run python scripts/categorize_invoices.py --input invoices.json --output categorized.json
6. Export: Generate accountant-ready CSV with summary Result: Organized expense report with VAT summary ready for accountant

Example 2: VAT Extraction from Receipts

User says: "I paid 5,850 NIS total for cloud services. What is the VAT portion?" Actions:

1. Apply the 18/118 rule: VAT = 5,850 * (18 / 118) = 892.37 NIS
2. Net amount: 5,850 - 892.37 = 4,957.63 NIS
3. Categorize: Communications (code 8) for cloud services
4. Note: Verify supplier is Osek Murshe and issued a tax invoice Result: VAT of 892.37 NIS extractable, net expense 4,957.63 NIS in Communications (8)

Example 3: Osek Patur Invoice Handling

User says: "I got an invoice from a freelance designer, but there is no VAT line" Actions:

1. Check: Is the supplier Osek Patur (עוסק פטור)?
2. If Osek Patur: No VAT to deduct, record full amount as expense
3. Categorize: Subcontractors (code 2) for freelance design work
4. Note: Request the supplier's TIN and verify their status Result: Full amount recorded as expense with no VAT deduction, flagged for accountant

Example 4: Mixed-Use Vehicle Expense

User says: "I got a fuel receipt for 2,340 NIS for a car I use for both work and personal trips" Actions:

1. Extract VAT: 2,340 * 18 / 118 = 356.95 NIS (total VAT)
2. Apply the vehicle rule: only 2/3 of VAT is deductible on a non-commercial vehicle
3. Deductible VAT: 356.95 * 2/3 = 237.97 NIS
4. Non-deductible VAT: 356.95 * 1/3 = 118.98 NIS
5. Categorize: Vehicle expenses (code 9) Result: Total VAT 356.95 NIS, but only 237.97 NIS is deductible. The remaining 118.98 NIS is a non-deductible expense.

Bundled Resources

Scripts

• scripts/categorize_invoices.py -- Categorizes Israeli invoices by Tax Authority expense codes (1–12), extracts VAT at 18%, validates business numbers (Luhn-like check digit), applies the vehicle 2/3 rule, and generates accountant-ready reports. Run: python scripts/categorize_invoices.py --help

References

• references/expense-categories.md -- Complete list of Tax Authority expense categories (codes 1–12) with descriptions and common examples, plus special rules: vehicle 2/3 deduction, entertainment 80% income-tax cap, mixed-use proportional deductions, depreciation rates by asset type. Consult when categorizing unusual expenses.

Gotchas

• Agents often calculate VAT as amount * 0.18 when extracting from a total, but the correct formula to extract VAT from a VAT-inclusive amount is total / 1.18 * 0.18 (or equivalently total * 18/118). This "1/6 rule" is specific to Israeli bookkeeping and the divisor changed from 117 to 118 when the rate moved to 18% in 2025.
• Osek Patur (exempt dealer) invoices have no VAT component. Agents may still try to extract VAT from these invoices, producing incorrect bookkeeping entries.
• Israeli invoice numbers are not globally unique. Different suppliers can have the same invoice number. Always index by supplier + invoice number combination.
• Hebrew OCR on scanned invoices frequently misreads the characters vav (ו) and zayin (ז), and confuses final-mem (ם) with samekh (ס). Verify extracted amounts and names.
• The SHAAM allocation-number threshold is staged (NIS 10,000 from 1 Jan 2026, dropping to NIS 5,000 from 1 Jun 2026). Apply the threshold that was in force on the invoice issue date, not today.
• The Ministry of Finance proposed a VAT rise to 19% for January 2026 during the 2026 budget talks. That proposal was rejected; the rate remains 18% through 2026. Do not pre-apply a 19% rate to invoices regardless of how confident the source looks.
• The Osek Patur turnover ceiling rose from NIS 120,000 to NIS 122,833 starting 2026. Agents that hardcode 120,000 will flag legitimate Osek Patur status as "over threshold" for revenues between 120,001 and 122,833.
• An invoice dated more than 14 days after the underlying supply or payment can be challenged by the Tax Authority. Flag suspiciously late invoices for the accountant.

Reference Links

Troubleshooting

Error: "VAT amount doesn't match"

Cause: Rounding differences between line-item VAT and total VAT Solution: Israeli invoices may have rounding differences of up to 1 NIS. Use the VAT amount printed on the invoice (not recalculated). If no VAT line exists, use the 18/118 rule from Step 3. Differences greater than 1 NIS usually indicate either the wrong rate (legacy 17%) or a real invoice error, contact the supplier for a corrected invoice.

Error: "Cannot determine business type"

Cause: Invoice does not clearly state Osek Murshe or Osek Patur Solution: Look for "עוסק מורשה" or "עוסק פטור" on the invoice. Check the TIN on the Tax Authority business lookup. If unclear, treat as Osek Patur (no VAT deduction) and flag for accountant review.

Error: "Expense category unclear"

Cause: Invoice description is vague or multi-category Solution: Use the primary purpose of the expense. When in doubt, assign to "Other expenses" (code 12) and let the accountant reclassify. Common confusion: software subscriptions belong in Communications (8), not Office expenses (11).

Error: "Missing SHAAM allocation number on a B2B invoice"

Cause: A B2B tax invoice above the active threshold was issued without a SHAAM allocation number (מספר הקצאה) Solution: Determine the threshold in force on the invoice issue date (NIS 20,000 in 2025; NIS 10,000 from 1 Jan 2026; NIS 5,000 from 1 Jun 2026). If the invoice is above the threshold and lacks an allocation number, it is not valid for VAT input deduction. Ask the supplier to reissue with an allocation number, or record the invoice without claiming the input VAT and flag for the accountant.