| 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. Activate for: ארגון חשבוניות, חשבונית, חשבונית מס, סיווג הוצאות, חילוץ מע״מ, עוסק מורשה, עוסק פטור, הכנה לרואה חשבון, הנהלת חשבונות, קבלות. 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, SquadCoder, Codex. Python 3.8+ for helper scripts. |
IL Invoice Organizer
Instructions
Step 1: Identify Invoice Type and Source
Determine what documents the user has:
| Document Type | Hebrew | VAT Reclaimable | Categorization |
|---|
| Tax Invoice (300) | חשבונית מס | Yes - extract VAT | Full categorization |
| Tax Invoice/Receipt (305) | חשבונית מס/קבלה | Yes - extract VAT | Full categorization |
| Receipt only (320) | קבלה | No VAT to reclaim | Payment record only |
| Credit Invoice (310) | חשבונית זיכוי | Yes - negative VAT | Reverse original category |
| Proforma (330) | חשבונית פרופורמה | No - not a tax document | For reference only |
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:
| Field | Hebrew | Where to Find | Validation |
|---|
| Supplier name | שם הספק | Header | Must match TIN |
| Supplier TIN | מספר עוסק | Header | 9 digits with check digit |
| Invoice number | מספר חשבונית | Header | Sequential |
| Date | תאריך | Header | DD/MM/YYYY format |
| Net amount | סכום לפני מע"מ | Line items sum | Before VAT |
| VAT amount | סכום מע"מ | VAT line | = Net * 0.18 |
| Total amount | סכום כולל | Bottom | = Net + VAT |
| Allocation number | מספר הקצאה | B2B invoices above SHAAM threshold | SHAAM allocation required |
SHAAM allocation threshold timeline (Israel Tax Authority, accelerated rollout):
| Period | Threshold (pre-VAT) |
|---|
| 2025 (full year) | NIS 20,000 |
| 1 Jan 2026 to 31 May 2026 | NIS 10,000 |
| From 1 Jun 2026 | NIS 5,000 (permanent floor) |
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_rate = 0.18
gross_amount = 1180
vat_amount = gross_amount * (vat_rate / (1 + vat_rate))
net_amount = gross_amount - vat_amount
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:
| Code | Hebrew | English | Common Examples |
|---|
| 1 | חומרי גלם | Raw materials | Production materials, components |
| 2 | קבלני משנה | Subcontractors | Freelancer invoices, outsourced services |
| 3 | שכר עבודה | Wages and salaries | Employee salaries, bonuses, commissions |
| 4 | ביטוח לאומי מעסיק | Employer NII | Employer share of Bituach Leumi |
| 5 | שכירות | Rent | Office, warehouse, shop, workshop rent |
| 6 | ביטוח | Insurance | Liability, professional, property, inventory |
| 7 | חשמל ומים | Utilities | Electricity, water |
| 8 | תקשורת | Communications | Phone, mobile, internet, cloud services |
| 9 | הוצאות רכב | Vehicle expenses | Fuel, maintenance, vehicle insurance, parking |
| 10 | פחת | Depreciation | Computers, furniture, equipment, vehicles |
| 11 | הוצאות משרד | Office expenses | Stationery, paper, toner, postage |
| 12 | הוצאות אחרות | Other expenses | Representation, travel, training, subscriptions |
Use scripts/categorize_invoices.py for automatic categorization.
Step 5: Identify Business Type
Determine supplier and customer business status:
| Status | Hebrew | VAT Treatment | Invoice Type |
|---|
| Osek Murshe | עוסק מורשה | Charges VAT, can deduct input VAT | Tax Invoice (300/305) |
| Osek Patur | עוסק פטור | No VAT charged (under threshold) | Receipt only (320) |
| Hevra Peratit (HP) | חברה פרטית (ח"פ) | Charges VAT, TIN starts 51/52 | Tax Invoice |
| Amuta (Non-profit) | עמותה | Usually no VAT, TIN starts 58 | Receipt |
| Malkar (Non-profit) | מלכ"ר | No VAT | Receipt |
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.
| Filing | Frequency | Threshold / Trigger | Deadline |
|---|
| VAT return (Doch Tkufati) | Bi-monthly | Annual turnover ≤ NIS 1.51M | 15th of the month after the period |
| VAT return | Monthly | Annual turnover > NIS 1.51M | 15th of the next month |
| Income tax annual return (Doch Shnati) | Annual | All self-employed | 30 April (paper) / 31 May (online); via מייצג can extend to Nov–Dec |
| Bituach Leumi advances | Monthly | All self-employed | 15th of next month |
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:
- Collect: Invoice images or text data from user
- Parse: Extract supplier, amount, VAT, date from each
- Categorize: Assign Tax Authority category per Step 4
- Validate: Check TIN format, VAT calculation, allocation numbers
- Run
python scripts/categorize_invoices.py --input invoices.json --output categorized.json
- 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:
- Apply the 18/118 rule: VAT = 5,850 * (18 / 118) = 892.37 NIS
- Net amount: 5,850 - 892.37 = 4,957.63 NIS
- Categorize: Communications (code 8) for cloud services
- 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:
- Check: Is the supplier Osek Patur (עוסק פטור)?
- If Osek Patur: No VAT to deduct, record full amount as expense
- Categorize: Subcontractors (code 2) for freelance design work
- 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:
- Extract VAT: 2,340 * 18 / 118 = 356.95 NIS (total VAT)
- Apply the vehicle rule: only 2/3 of VAT is deductible on a non-commercial vehicle
- Deductible VAT: 356.95 * 2/3 = 237.97 NIS
- Non-deductible VAT: 356.95 * 1/3 = 118.98 NIS
- 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.
