taxes

Commandline quarterly tax calculator for simplified Ukrainian taxation system

Installing

go install github.com/mxmCherry/taxes/v2@latest

To call the binary without specifying full path, $GOBIN can be included in your $PATH:

export GOBIN=$HOME/go/bin # GOBIN defaults to ~/go/bin
export PATH=$PATH:$GOBIN

Using

# works with ~/.taxes/data.yaml by default
taxes

# or file(s) can be explicitly specified
taxes data1.yaml data2.yaml

Input file must be a YAML-encoded data with the following format:

business:
  base_currency: UAH    # base/local business currency
  tax_rate: 0.05        # tax rate, 5%
  rounding_precision: 2 # round to 2 decimals after comma (to kopecks); do not specify or set to 0 to disable rounding
transactions:
  - time: 2021-01-01T09:45:53Z # transaction time/date
    amount: 100.12             # transaction amount (possibly in foreign currency)
    currency: USD              # transaction currency code (possibly foreign currency)
  ...

Every bit of data mentioned above must be provided.

Transactions must be ordered by time, oldest to newest.

This tool prints (STDOUT) simplified table output with per quarter and annual (cumulative, since beginning of the year) income/taxes:

          Year |            QQ |        Income |           Tax | Annual Income |    Annual Tax |
               |               |               |               |               |               |
          2020 |            Q1 |        100.00 |          5.00 |        100.00 |          5.00 |
          2020 |            Q3 |        200.00 |         10.00 |        300.00 |         15.00 |
               |               |               |               |               |               |
          2021 |            Q1 |        100.12 |          5.01 |        100.12 |          5.01 |

Notes

This CLI tool reads/parses YAML-encoded input file data into memory, pulls/calculates missing data (currency rates, income, tax amounts etc) and prints result to STDOUT.

It is recommended to comment out previous year data or keep each year in own file to pull currency rates less frequently: that's the slowest bit, and now this tool includes hardcoded rate-limiting to query bank.gov.ua APIs (~150ms between requests).

Rounding

Providing non-zero rounding_precision (decimals after comma) enables rounding. It makes sense to use rounding_precision: 2 to round to kopecks.

Rounding is applied in the following cases:

• each currency conversion, so only to non-base_currency transactions
• currency rates themselves are not rounded at all
• local-currency transactions are not rounded at all
• rounding is applied to quarter, only in the end (once transaction amounts are summed)
• quarter rounding is applied to income first
• and then it is applied to tax (using already-rounded income amount)
• and then annual (cumulative) amounts are rounded as well (only to get rid of float64 precision loss errors, doesn't affect normal (kopecks etc) precision)

Rounding behavior is the usual one: x >= 0.5 is rounded up, x < 0.5 is rounded down.

Rounding can be disabled by not specifying it (or specifying rounding_precision: 0).

Migrate from previous major version (v1)

Simply rename:

• company: -> business:
• payments: -> transactions:
• date: -> time: (for each transaction)

v1 can still be installed with:

go install github.com/mxmCherry/taxes@v1.0.0