ICMS in Depth · TF Fiscal API

ICMS (Imposto sobre Circulação de Mercadorias e Serviços) is Brazil's heaviest and most intricate tax: each of the 27 states legislates its own version on goods, interstate transport and communication services. It is non-cumulative (input credits), tax-inclusive (the tax is part of its own base) and subject to numerous state exceptions: tax substitution (ST), base reductions, deferral, exemptions and the interstate differential (DIFAL).

Computation and rates

Tax-inclusive base: base = price (which already contains ICMS) + freight + insurance + other charges − discounts; IPI joins the base when selling to a final consumer. A nominal 18% is an effective ~21.95% on the net price.
Internal rates: set by each state, mostly 17%–20% (São Paulo 18%, Rio 20% plus 2% FCP, Minas 18%…); “non-essential” goods such as tobacco, alcohol and cosmetics reach 25%–35%.
Interstate rates: 12% in general; 7% from the South and Southeast (except Espírito Santo) to the North, Northeast, Centre-West and Espírito Santo; imported goods (origin 1, 2, 3, 8) always 4%.
DIFAL: on interstate sales to non-taxpayers (individuals, companies without ICMS registration), the difference between the destination internal rate and the interstate rate goes to the destination state and is paid by the seller; Simples (CRT 1 / 4) is exempt (ADI 5469), CRT 2 / 3 must compute it.
FCP (poverty fund surcharge): some states add 1%–2% on certain goods; on interstate sales it follows the DIFAL to the destination state.
Tax substitution (ST): for listed goods (identified by CEST), the ICMS of the whole chain is withheld once by the manufacturer or importer on a base marked up by the MVA; downstream resellers use CST 60 / CSOSN 500 and charge nothing.
Base reduction, exemption, deferral, suspension: granted by each state per product, mapped to CST 20 / 40 / 51 / 50 under the regular regime; Simples has no such split and uses CSOSN 400 / 300 for non-taxed and immune.

The regime decides between CSOSN and CST

CRT	Regime	ICMS code	Company invoice_type	DIFAL
`1`	Simples Nacional	CSOSN · 3	`simples_nacional` / `1`	Exempt
`2`	Simples Nacional above the state sub-limit	CST · 2	`simples_nacional_excesso` / `2`	Due
`3`	Regular regime (Lucro Real / Presumido)	CST · 2	`tributacao_normal` / `lucro_normal` / `3`	Due
`4`	MEI	CSOSN · 3	`simples` / `4`	Exempt

The platform validates locally that code length matches the regime: CRT 1 / 4 sending a CST, or CRT 2 / 3 sending a CSOSN, is rejected with the reason and never forwarded (it would be rejected with 590 / 591 and consume the CNPJ's call quota). No check when invoice_type is outside the table.

Simples Nacional: CSOSN table

CRT 1 and 4. Send 3 digits in icms.situacao_tributaria; all 10 are supported.

CSOSN	Meaning	When to use
`101`	Taxed under Simples with credit allowed	Sale to a regular-regime taxpayer passing on the ICMS credit; fill `aliquota_credito` (1.25%–3.95% by revenue band).
`102`	Taxed under Simples without credit	Most common: sales to consumers, non-taxpayers, or any sale without credit transfer.
`103`	ICMS exemption for the revenue band	When the state exempts the lower revenue bands.
`201`	Credit allowed, ICMS-ST withheld	Selling ST goods as the substitute while passing on the credit.
`202`	No credit, ICMS-ST withheld	Selling ST goods as the substitute; the usual ST case.
`203`	Exempt for the band, ICMS-ST withheld	103 combined with ST.
`300`	Immune	Constitutional immunity: books, newspapers, periodicals and their paper; exports.
`400`	Not taxed	Outside ICMS: non-sale dispatches such as gifts, samples, repairs.
`500`	ICMS already charged via ST or advance payment	Reselling ST goods; pair with CFOP 5405 / 6404, optionally with withheld values (`v_bc_st_ret`, `v_icms_st_ret`).
`900`	Others	When nothing above fits: imports, cases needing base and amount together.

Regular regime: CST table

CRT 2 and 3. Send 2 digits in icms.situacao_tributaria; the XML prefixes the origin to make 3 digits. All 15 are supported.

CST	Meaning	When to use
`00`	Fully taxed	Most common regular sale; fill `aliquota`.
`10`	Taxed with ICMS-ST withheld	Selling ST goods as the substitute; fill `aliquota_mva`, `aliquota_icms_st`.
`20`	Reduced calculation base	State base reduction; fill `aliquota_reducao` (reduction %).
`30`	Exempt or not taxed, with ICMS-ST withheld	Own operation exempt but ST withheld for the next link.
`40`	Exempt	Explicitly exempt by state law; may carry `motivo_desoneracao` and `valor_desoneracao`.
`41`	Not taxed	Outside the ICMS scope; common for exports.
`50`	Suspension	Temporary dispatches: repair, demonstration, toll manufacturing.
`51`	Deferral	Tax deferred to a later link; fill `aliquota_diferimento`.
`60`	ICMS already charged via ST	Reselling ST goods; pair with CFOP 5405 / 6404.
`70`	Reduced base with ICMS-ST withheld	20 combined with 10.
`90`	Others	When nothing above fits.
`02` · `15` · `53` · `61`	Single-phase fuel taxation series	Fuel sector only (02 own, 15 with withholding, 53 deferred, 61 already charged); fill `ad_rem_icms`.

Product origin (origem)

Field products[].origem, required under both regimes. It drives the interstate rate (4% for imported goods) and becomes the first digit of the CST/CSOSN in the XML.

Value	Meaning
`0`	National, except 3, 4, 5 and 8
`1`	Foreign, direct import (except 6)
`2`	Foreign, bought on the domestic market (except 7)
`3`	National, import content above 40% and up to 70%
`4`	National, made under basic production process rules
`5`	National, import content of 40% or less
`6`	Foreign, direct import, no national equivalent (CAMEX list)
`7`	Foreign, bought domestically, no national equivalent (CAMEX list)
`8`	National, import content above 70%

Platform fields (category icms[] row / inline impostos.icms)

Field	Purpose
`cenario` · `tipo_pessoa`	Row keys: scenario and person type, see below.
`codigo_cfop` · `situacao_tributaria`	Operation code and CST/CSOSN; required.
`aliquota`	ICMS rate (%).
`aliquota_reducao`	Base reduction % (CST 20 / 70).
`aliquota_fcp`	FCP surcharge rate (%).
`aliquota_mva` · `aliquota_icms_st` · `aliquota_reducao_st` · `aliquota_fcp_st`	When withholding ST as the substitute: MVA mark-up, ST rate, ST base reduction, FCP on ST (CST 10 / 30 / 70, CSOSN 201 / 202 / 203).
`v_bc_st_ret` · `v_icms_st_ret` · `v_icms_substituto` · `p_fcp_st_ret` · `v_bc_fcp_st_ret` · `v_fcp_st_ret`	When reselling ST goods (CST 60 / CSOSN 500): base and amounts already withheld upstream.
`aliquota_credito`	Credit rate passed to the buyer under Simples (CSOSN 101 / 201).
`aliquota_diferimento`	Deferral % (CST 51).
`motivo_desoneracao` · `valor_desoneracao`	Exemption reason code and waived amount (CST 40 / 41 / 50 / 90).
`beneficio_fiscal[]`	State tax benefit codes: `[{"estado":"SP","codigo":"SP800001"}]`, written to cBenef in the XML.
`disable_difal` · `difal_desconta_icms_inter` · `difal_base_por_dentro` · `v_bc_uf_dest`	DIFAL controls: disable it; use the “double tax-inclusive” base net of interstate ICMS (most states' method); or pass the destination base directly.
`desconta_icms_pis_cofins`	When true, subtract the line's ICMS from the PIS/COFINS base (Supreme Court Tema 69).

Scenarios and person type in the category

cenario	Meaning
`saida_dentro_estado`	Outbound, recipient in the same state
`saida_fora_estado`	Outbound, recipient in another state
`entrada_dentro_estado`	Inbound, counterparty in the same state
`entrada_fora_estado`	Inbound, counterparty in another state
`padrao`	Default row when no specific scenario matches

Lookup order: current scenario → padrao → legacy saida_dentro_estado / saida_fora_estado; each step filters by tipo_pessoa (fisica / juridica) first.
Interstate sales to individuals need the saida_fora_estado + fisica row with CFOP 6108 and codes, otherwise the company row is used.
Import (transaction_type = 2) ignores scenarios, takes the first record and prefers CFOP 3.xxx; export (= 3) ignores tipo_pessoa.
If no row matches, issuance fails and the error names the missing cenario and tipo_pessoa.

Recommended combinations

Operation	Simples Nacional (CRT 1 / 4)	Regular regime (CRT 3)
Regular sale	CSOSN `102`（`101` + `aliquota_credito`）	CST `00` + `aliquota`
Resale of ST goods	CSOSN `500` · CFOP 5405 / 6404	CST `60` · CFOP 5405 / 6404
Withholding ST as the substitute	CSOSN `202` / `201` · MVA	CST `10` · MVA
Interstate sale to individuals (B2C)	CSOSN `102` · CFOP 6108 · 免 DIFAL	CST `00` · CFOP 6108 · DIFAL + FCP
Non-sale dispatch (gift, sample, repair…)	CSOSN `400`	CST `41`（送修 `50`）
Export	CSOSN `300` · CFOP 7101 / 7102	CST `41` · CFOP 7101 / 7102
Import inbound	CSOSN `900` · CFOP 3102	CST `00` · CFOP 3102

Rates, reliefs and ST lists are set by each state and change often; figures here are typical values, and your accountant and state rules prevail. For CFOP choices see “CFOP by Scenario”.