Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Taxi Driver - A Flexible International Tax Engine Microservice

Built with Micro & Lowdb ⚑️


Build Status Maintainability Test Coverage

taxi driver


Supported Countries

  • πŸ‡²πŸ‡½MΓ©xico
  • πŸ‡¦πŸ‡·Argentina
  • πŸ‡ΈπŸ‡¦Saudi Arabia

*Full tests & specification for each country can be found at tests/integration

Tax Rules

Tax Rules are defined in a LowDB located at db.json#L18

These rules are matched and applied based on the provided Query.

Validity range

A range of Datetime values for specifying the validity of a rule

Currency & decimals precision

Taxi Driver use Currency.js for all Currency calculations, thus getting rid of decimals rounding issues.

For currency amounts the default number of cents is 2

For the rate factors the precision is set to 8 using the FACTOR_PRECISION constant.


A query includes the following (case insensitive) fields:

Required parameters

Initially, these required parameters are used to filter out the tax rules by:

  • country (String): Country code
  • taxes (Array(String)): Name(s) to identify the taxes

Optional match params

Optional match params (defined at db.json#L3) are used to "best match" a single rule while querying the app via the API:

  • region: Region (ex. border tax, state, county, municipality)
  • bpType: Business Partner type
  • txType: Transaction type
  • docType: Document type
  • category: Category name (ex.: for products)
  • area: Area (ex.: business area, service station)

Optional vars object.

vars object is used both in a query and rules, to store variable dependant values (such as sub-totals), and other formulas to be evaluated by the FormulaParser.

*Commonly used for: subTotal, unitPrice, ...

Array of taxes

An array of String's to be matched against rule(s) taxName

Formulas & Variables

*Both vars, rate & amount can also be String's, as they can be evaluated using handsontable/formula-parser

Query Example

  country: "sa",
  txType: "sales",
  docType: "invoice",
  category: 'DRUG',
  bpTaxType: 'TAXYES',
  area: undefined,
  vars: {
    unitPrice: 5000
  taxes: ['VAT'],

Rule Matching

The query above will match to the following rule(s):

      "countryCode": "sa",
      "txType": "sales",
      "docType": "invoice",
      "taxName": "VAT",
      "category": "DRUG",
      "bpTaxType": "TAXYES",
      "rate": "IF(unitPrice > 2000, 0.02, 0.05)"


Postman collection:

GET /countries

GET /rules

POST /taxes


  country: "sa",
  // ... match params
  vars: {
    // ...
  taxes: [ /* ... */ ]


  taxes: {
    [taxName]: {
      rate: {error: /*...*/, result: /*...*/},
      // ...
    [taxName]: {
      rate: {error: /*...*/, result: /*...*/},
      // ...

Advanced Usage

meta object

Rules can have a meta object, containing any informative fields that need to be passed to the consumer. For example, an exempt flag for Mexico's particular exempt taxes.

Factor, amounts & totals calculation

If a vars.subTotal is provided, the engine will automatically calculate and return:

  • totals (taxTotal & grandTotal) in the response header.
  • amount & factor per tax

Dependant Tax Factors

Rules can have a dep string with the name of a dependant taxName that has to be used to calculate the factor

GUI (alpha version)


Easy development using zeit/micro-dev:

yarn run dev


Jest is used for both unit & integration tests. Run with:

yarn test

Inspired by

Spec docs


πŸš–A flexible & international Tax Engine Microservice




No releases published


No packages published