Create or update a VAT rate (or sales tax / GST / etc. rate, depending on what taxation is used in the particular country).

To get a list of all tax rates, see getVatRates.

Input parameters

Parameter name Description Possible value Required
vatRateID Integer
name VAT rate name. Use either general parameter "name" or one or more of the following parameters if you need to set the names in specific languages. String yes
nameEST String
nameENG String
nameLAT String
nameRUS String
nameFIN String

VAT / tax rate.

When creating a new tax rate, this field is required (unless you are creating a reverse VAT, see below) and it must be a non-negative decimal. A value of 0 is allowed as well.

On an existing tax rate, this field can not be edited; API will ignore the input.

code Corresponding VAT code in accounting software String

0 or 1, by default 1.

A tax rate can be "archived" by setting active = 1; this tax rate will then no longer appear in tax rate drop-downs.


0 or 1, by default 0.

Reverse VAT is a concept used in Europe. It means that in certain cases, the obligation to pay VAT (value-added tax) lies on the buyer, not the seller. A seller can issue an invoice where one or multiple lines are subject to reverse VAT. This amount of VAT must then be paid by the buyer directly to the Tax Department, and this VAT amount is not included in the total sum payable to the seller.

To create a Reverse VAT rate, leave the rate field unspecified. (Otherwise API returns error 1013.) Set the flag isReverseVat to 1 and specify the rate percentage (eg. 18.5 for 18.5%) in the field reverseRate. Reverse rate can also be 0%.

If you populate the field "isReverseVat", then "reverseRate" must be defined as well, and vice versa. Otherwise API returns error 1016.

On an existing tax rate, the "isReverseVat" field cannot be edited any more. Populating this field (even if the value is same as previously) will trigger error 1013.


Reverse tax rate.

Must be a non-negative decimal. If you specify an invalid value (eg. text), API returns error 1014.

On an existing tax rate, the "reverseRate" field cannot be edited any more. Populating this field (even if the value is same as previously) will trigger error 1013.

gstExemptTaxRateID Specific field for Canada and US, ID of corresponding reduced tax rate. Must be existing and active tax rate ID Integer
***** Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...). When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
attributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. String
attributeType# Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'. String
attributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number.
**** NB! In Erply, only one tax can be applied to a sale. Even if your local authorities are in effect levying multiple sales taxes / GSTs, you need to combine these and define it in Erply as a single total tax rate.

For reporting purposes you can divide the tax into sub-components. A tax rate can have any number of sub-components, but a component must belong into one of 4 fixed categories, and it rarely makes sense to define two components that share the same category.

Following the US sales tax model, the categories are:
  • STATE (state sales tax),
  • COUNTY (county sales tax),
  • CITY (city sales tax),
  • OTHER,
but you can use them for your own custom setup if needed.

API saveVatRate does not allow to directly create more than one of any sub-components; you can create one of each type through the state and stateTaxRate, county and countyTaxRate, city and cityTaxRate, otherTaxName and otherTaxRate input fields. Use saveVatRateComponent if you need multiple components with same type.

To delete a component, use deleteVatRateComponent.

The following input fields can be used only if the "City, county and state tax rates" module has been enabled on your account.

Also, make sure that the component tax rates, when added up, equal the total tax rate. Eg. if state tax is 5%, county tax is 3% and city tax is 0.75%, make sure that you set rate = 8.75.
ZIPCode Fill this field to specify that this tax rate, or this specific combination of city, county and state tax rates, is used in a specific ZIP code area. There are web services that, given a specific US ZIP code as input, can return a list of sales tax rates that must be applied. String
category String
state State name. String
stateTaxRate Percentage of state sales tax. Decimal
county County name. String
countyTaxRate Percentage of county sales tax. Decimal
city City name. String
cityTaxRate Percentage of city sales tax. Decimal
otherTaxName Naming for custom sales tax component. String
otherTaxRate Percentage of custom sales tax component. Decimal


Field name Type Description
vatRateID Integer ID of the newly-created or updated item