Artifi Logo
All Plugins

Estonian Payroll Calculator

v1.0.0Estonia

Gross-to-net payroll with TSD declaration

A complete Estonian payroll calculation engine that processes gross-to-net for all employees in a payroll run. Applies all Estonian tax formulas: 33% social tax (employer), 22% income tax, 1.6% unemployment insurance (employee), 0.8% unemployment insurance (employer), and funded pension at 2%, 3%, or 6% depending on the employee's tier. Handles the basic tax exemption, pre-tax and post-tax voluntary deductions, and pro-rating for mid-month starts/exits. Generates TSD declaration XML files for direct upload to the EMTA (Estonian Tax and Customs Board) portal.

View on GitHubClone repository

Commands

/calculate-payroll

Calculate gross-to-net payroll for all employees in a payroll run. Loads the payroll run, fetches employees with compensation/tax settings/deductions, applies all Estonian tax formulas, validates net pay within 0.02 tolerance, and submits calculated results. Shows summary table with per-employee breakdown.

/generate-tsd

Generate the Estonian monthly TSD declaration XML for EMTA filing. Fetches calculated payroll data, builds structured JSON input, and runs the generate_tsd.py script to produce validated XML with correct namespace and per-employee data (personal ID, gross pay, income tax, social tax, unemployment, pension).

How It Works

Payroll Calculation

  1. 1

    Load payroll run and verify status is "draft"

  2. 2

    Fetch all active employees with compensation records, tax settings, and voluntary deductions

  3. 3

    Load Estonian tax rates from payroll tax jurisdiction configuration

  4. 4

    For each employee: calculate gross pay (pro-rated if mid-month start/exit)

  5. 5

    Calculate employee deductions: unemployment insurance (1.6%), funded pension (2%/3%/6%)

  6. 6

    Apply pre-tax voluntary deductions

  7. 7

    Calculate taxable income = gross - unemployment - pension - pre-tax deductions - basic exemption

  8. 8

    Calculate income tax = max(0, taxable income x 22%)

  9. 9

    Apply post-tax voluntary deductions

  10. 10

    Calculate net pay = gross - all employee taxes and deductions

  11. 11

    Calculate employer costs: social tax (33%), employer unemployment (0.8%)

  12. 12

    Validate: net pay = gross - total taxes - total deductions (within 0.02 tolerance)

  13. 13

    Submit calculation results and show summary table

TSD Declaration Generation

  1. 1

    Fetch calculated or approved payroll run data

  2. 2

    Build structured JSON input with per-employee tax details

  3. 3

    Run generate_tsd.py script to produce validated XML

  4. 4

    Output includes header, summary totals, and Annex 1 per-employee lines

  5. 5

    XML ready for upload to e-MTA portal

Validation Checkpoints

Every run must pass these checks before proceeding. If any checkpoint fails, the workflow stops and reports the issue.

Payroll run exists and is in "draft" status

All employees in the run have active compensation records

All employees have tax settings (pension tier, basic exemption)

Tax rates loaded from payroll tax jurisdiction (country_code = "EE")

For each employee: net pay equals gross minus total taxes minus deductions (within 0.02)

Submission succeeds without validation errors

Reference Data Included

Structured knowledge files that drive the plugin's logic. These contain formulas, templates, and regulatory rules — not hardcoded values.

estonian-tax-formulas.md

Complete tax rate formulas: 22% income tax, 33% social tax, 1.6%/0.8% unemployment, 2%/3%/6% pension tiers, basic exemption rules

submission-format.md

JSON structure for payroll calculation submission with per-employee tax lines and deduction details

tsd-declaration.md

TSD structure with Header, Summary, and Annex 1 per-employee field reference

Built for Artifi, open for everyone

This plugin is designed to work out-of-the-box with the Artifi MCP server for full automation — Claude fetches your data, runs calculations, validates results, and submits entries automatically.

You can also download and adapt it to your own needs. The skills, commands, validation logic, and reference data are all open source. Swap the MCP tool calls for your own backend, or use the reference files as standalone knowledge resources for your Claude projects.

Subscribe to new posts

Get notified when we publish new insights on AI-native finance.