Cargon ICMS Library

• Website: https://cargon.com.br/
• ICMS Library with two main functionalities:
  • findTaxBracket( ): Find up-to-date ICMS tax brackets data, including exempt states.
  • calculateIcms( ): ICMS calculator with an "inside" operation and reduction of calculation base.

Usage

npm install @cargon_logtech/icms

Then require or import the functions before start using it

import { findTaxBracket, calculateIcms } from '@cargon_logtech/icms';

//OR

const icms = require('@cargon_logtech/icms');

findTaxBracket( )

This function queries our up-to-date database and returns the tax bracket data for in-state or interstate transactions, even when they are exempt from taxes.

• Inputs:

  first parameter = origin state. ("PR", "SP", "MG", ...)

  second parameter = optional destination state. ("SP", "RJ", ...)

• Outputs:

  bracket = tax bracket percentage in an integer number. (12 = 12%, 7 = 7%).

  legal_text = legal text regarding an specific state policy, if there is one.

import { findTaxBracket } from '@cargon_logtech/icms'

const result = findTaxBracket("PR", "PR");
/*
 result = {
    bracket: 0,
    legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
 }
*/

In-state transaction

• Transaction where the origin state is the same as the destination state.
• The second parameter is optional, if you dont include it, we will consider the destination state the same as the origin state, meaning an in-state transaction.

const result = findTaxBracket("PR", "PR");

// OR

const result = findTaxBracket("PR");
/*
   result = {
    bracket: 0,
    legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
   }
*/

Interstate transaction

• Transaction where the destination state is different from the origin state.
• In this case, you are required to inform the second parameter of the function.

const result = findTaxBracket("ES", "SP");

/*
   result = {
      bracket: 12,
      legal_text: null
   }
*/

Observation & other cases:

1. No data found: if no data about the states inputted in the functon was found, we will throw an error.

2. State is exempt from taxes: if the state has an exempt policy and doesn't have tax brackets, we will return 0 as the "bracket" result:

{
   bracket: 0, //Tax bracket = 0%, meaning it is exempt from taxes
   legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
}

3. Legal text: if there is an legal text, we will return it; otherwise, we will return null

{
   bracket: 12,
   legal_text: null //No legal text
}

calculateIcms( )

Function that calculate ICMS tax bracket with an "inside" operation.

• Required input object "values":

  ammount = initial ammount used to calculate the new calculation base.

  bracket = percentage of tax bracket being applied to the calculation base. (20 = 20%, 3 = 3%)

  reducedBasePercentage = optional percentage that will reduce the calculation base ammount. (13 = 13%, 8 = 8%)

• Optional input object "options":

  decimals = the level of precision in regards to the decimal values being returned.

• Outputs:

  initialAmmount = initial ammount inputted by the user.

  icmsPercentage = tax percentage inputted by the user.

  baseReductionPercentage = base reduction percentage inputted by the user (if there's one).

  icmsAmmount = ammount of ICMS tax bracket. The result of applying the ICMS percentage into the calculation base.

  calculationBase = calculation base used to calculate the Tax Bracket. Can be inferred as the final ammount.

  insidePercent = percentage of the ammount inputted by the user compared with the total ammount (initial ammount + tax bracket)

import { calculateIcms } from '@cargon_logtech/icms'

const result = calculateIs(
   {
      ammount: 1000,
      bracket: 18,
      reducedBasePercentage: 20, //OPTIONAL
   },
   {
      decimals: 2, //OPTIONAL
   }
);

/*
 result = {
  initialAmmount: 1000,
  icmsPercentage: 0.18,
  baseReductionPercentage: 0.2,
  calculationBase: 975.61,
  icmsAmmount: 175.61,
  insidePercent: 0.82
}
*/

Base reduction

• The base reduction percentage is applied directly into the calculation base, reducing its ammount.
• If you don't want to apply it, you simply put "0" in the field, or don't even include it in the parameters.

const result = calculateIcms(
   {
      ammount: 1000,
      bracket: 18,
      reducedBasePercentage: 0,
   },
   {
      decimals: 2,
   }
);

//OR

const result = calculateIcms(
   {
      ammount: 1000,
      bracket: 18,
   },
   {
      decimals: 2,
   }
);

/*
 result = {
  initialAmmount: 1000,
  icmsPercentage: 0.18,
  baseReductionPercentage: 0,
  calculationBase: 1219.51,
  icmsAmmount: 219.51,
  insidePercent: 0.82
}
*/

Exempt from taxes

• The percentage of ICMS tax bracket being applied into the calculation base.
• If the calculation is for an exempt state, simply put 0 into the "bracket" field.

const result = calculateIcms(
   {
      ammount: 1000,
      bracket: 0,
      reducedBasePercentage: 10,
   },
   {
      decimals: 0,
   }
);

/*
 result = {
  initialAmmount: 1000,
  icmsPercentage: 0,
  baseReductionPercentage: 0.1,
  calculationBase: 900,
  icmsAmmount: 0,
  insidePercent: 1
}
*/

Observations

1. Percentage is returned in decimals: All the percentage values used in the calculation are returned in decimals. If you want to convert them to integer, multiply them by 100.

2. Percentages are applied in the calculation base: Both the icms percentage and the base reduction percentage are applied in the new calculation base, not necessarily in the ammount inputted by the user. That's how the calculation works.