How to fit Brazilian complex taxes in ERPNext taxes

Hello all! Have a long time that I started to try localize ERPNext to Brazil, but have a single point that dont fit, this point is named Tax.

Let me explain 50% of one of our taxes

Tax Substituition - ICMS ST

Tax Substitution is the legal principle which allows, from that provided by law, the possibility of giving the other person, the condition responsible for payment of tax on taxable event practiced by others.

The ICMS ST or Tax Substitution (In Portuguese “Substituição Tributária) is taxation scheme used by federal and state governments in Brazil created to avoid double taxation and tax evasion and it facilitates the enforcement of taxes that are levied several times during the production of goods and provision of services in Brazil.

The Tax Substitution assigns responsibility to the taxpayer to pay the tax owed by his customer. The replacement will be collected by the taxpayer and subsequently to the government. The incidence of tax substitution is defined depending on the product or service in question and responsibility takes place in relation to goods or services provided by the law of each state.

The ICMS Tax Substitution was implemented because it was found that few manufacturers sell their products to thousands of distributors and resellers, and these last used to evade ICMS.

Parts of the text below were extracted from Federal and State Government websites where ICMS ST regulation is stated or other sources.

The transaction of ST involves two types of taxpayers:
• Substitute taxpayer(Contribuinte Substituto): He is responsible for the retention and payment of the tax. Usually it is the manufacturer or importer responsible to the subsequent operations.
• Substituted taxpayer (Contribuinte Substituído): He has the tax due on the operations and services paid by the substitute taxpayer.

Types of Substituição Tributária

There are three types of Tax Substitution, as follows:

  1. Antecedent Tax Substitution (Substituição tributária antecedente): where the law chooses the time and responsible for collecting the tax from taxpayers involved in the previous steps, the purchaser or recipient of the product, as is the case of deferral, which has set the close of the command and the taxpayer responsible for gathering exaction. The ST in relation to subsequent operations is characterized by the assignment of a particular taxpayer (usually the first in the marketing chain, the manufacturer or importer) to pay the value of ICMS due in subsequent operations with the goods until his departure meant the consumer or end user.

  2. Concomitant Tax Substitution (Substituição tributária concomitante): determines the need for the instant payment as the triggering event occurs. This kind of substitution regime is characterized by the allocation of liability for payment of tax to another taxpayer, and not one who is performing the operation or provision of service, concomitantly with the occurrence of a triggering event. This species is the Tax Substitution of cargo transportation services.

  3. Subsequent Tax Substitution (Substituição tributária subsequente): futures tied to events (also called tax replacement forward), applying to cases relating to our regulation (beer, mineral water, cigarettes, ice cream, new vehicles, tires, cement, etc.). Fixing margins profit and those responsible for this obligation. This is the best known type.


Assuming, for example, a product with a value of BRL 10.00, which was originated in the state of Rio de Janeiro, and is to be sold in the state of São Paulo. If this operation covers substitutição tributária for the ICMS tax, the government will provide for an agenda (normally a presumed resale value, for example, BRL 20.00). Assuming that under the interstate operation between SP and RJ partners the rate of ICMS is 12%, and on operations in intrastate SP partners the rate of is 18%, total ICMS will be calculated as follow:

Total ICMS-Normal = (BRL 10.00 x 12%) = 1.20 Total-ICMS Substitution = (BRL 20.00 x 18%) = 3.60
As the ICMS is calculated as a debit and credit, the amount collected would look like:
3.60 – (1.20) = BRL 2.40

Some advantages derive from the system of ST:

– For taxpayers: The tax substitution centralizes the collection of the tax due on the taxpayer by a third party replacement, facilitates the monitoring and encourages equality in taxation, preventing unfair competition between taxpayers who collect and those who do not regularly collect their taxes.
With the VAT / ST, business operations earn agility and simplicity in the issuance of tax documents and bookkeeping, and mitigate distortions and competition between taxpayers in the same field of activities.

– For society: The system of tax substitution is an important tool used by the state to broaden its revenue base, facilitating the monitoring and reducing tax evasion, revenue generating benefits to society.

The basic concept of VAT / ST is that the consumer is the taxpayer’s tax, but the tax will be paid in advance by the industry, incorporating the cost of the tax charged on the invoice value. The taxpayer is the ultimate consumer, which will be replaced in the obligation to pay the tax by industry, that’s where the name comes from: Substituição Tributária.

So, I understand how to contabilize and calcutate the tax, what I dont understand is if have a way using the smart schema of tax calculation in ERPNext to calculate something like this.

If the description of the tax is not clear, or left you confused, let me know, you are not alone!

@max_morais_dmm best to see what Odoo does. I am sure the Odoo community might have figured this out.


This seems to be more comprehensive GitHub - OCA/l10n-brazil: Localização brasileira oficial do Odoo.. You might just want to start porting this one by one!

Odoo seems to have a very active Brazil community, once you port these, many of them might want to switch to ERPNext!

@rmehta the schema that Odoo allow the taxes are distinct if compared with ERPNext

I can’t hook taxes in ERPNext

@max_morais_dmm won’t adding custom fields help?

@rmehta, no, because is not only about custom fields!

It’s about variables

See, certain fields have a group of variables to define the tax, if I add custom fields for taxes, I’ll have more than 80 fields! I’ts crazy and very hard to reach!

If I create custom doctypes, the calculated tax in the doctypes, dont match with the value calculated in the ERP

Here, is a small case that a sub-table in taxes tables will be great!, because all values are only variables, that will be used to calculate the tax.

The major issue here is that, I dont know if the model that ERPNext use today to calculate taxes are flexible to understand that:

For calculate a tax value, I can have discounts, additions, and type variables used in the taxes

Create the custom fields that are used for the value. Keep the rest in custom doctype and link your doctype to the tax table.

@rmehta, make sense but how I’ll avoid the standard calculation?

@max_morais_dmm overwrite it.

Also best to start with simpler features and start releasing something, so you get more momentum / confidence / collaborators!

Any news on this topic?

I’m the responsible for this version of brazilian localization for version 10 of Odoo:

Basically we avoid the Odoo standard calculation and we add those variables overriding some core methods.
Also here we added the concept of eletronic document for generate the “NFe”, also we have some modules for integration with delivery carrier “Correios” and “Boletos” documents for receive payments.

There is a lot of code that maybe could be reused for ErpNext.

Look this tax “ICMS ST”:

Around six parameters to calculate, not taking in consideration the variables used to filter this tax rule.

@rmehta, haven’t explored the details but I wonder if something similar to the way payroll components are calculated in payroll structures wouldn’t be a more flexible way to configure taxes in ERPNext. Basically, tax codes would be analogous to payroll structures containing a template for calculation of the tax value based on data from the invoice as well as other components. Would be a radical change though. I wonder if there’s appetite for that?


1 Like

@Chude_Osiegbu yes we can also pre-set Salary Structure based on this. You can bootstrap any documents you want at the time of setup / company creation by calling from the erpnext.[country].setup.setup method

This is important for many countries.To @Chude_Osiegbu 's suggestion I created a github issue a while ago. This would make tax rules very flexible.

1 Like

Just to add… If this can also be combined with true item-wise taxes that would be even better.


Hi… Have you had some new consideration, or evolution about our crazy tax structure?

@xickomesquita there’s no support for our tax system in ERPNext, but what can be done if mimic that using custom doctypes, and linking the custom doctypes to the tax table.

To avoid ERPNext to calculate the taxes you should use the “Actual” tax type for all taxes, and fetch the individual calculated from the custom doctypes.

These guys came up with a method that could probably be adjusted for your scenario…

@trentmu we’re talking about taxes under invoice, Brazilian Payroll may can be fit using that schema, invoices not.

Hi @max_morais_dmm … I’m also Brazilian. I’d like to know if there’s any way we can talk? Email or mobile would be great.

BTW my personal email is


Olá @Michael_Mallmann claro que sim

11 94724-8832