Search

saveVatRate

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 nameDescriptionPossible valueRequired
vatRateIDInteger
nameVAT 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
nameESTString
nameENGString
nameLATString
nameRUSString
nameFINString
rate

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.

Decimal
codeCorresponding VAT code in accounting softwareString
active

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.

Integer
isReverseVat

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.

Integer
reverseRate

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.

Decimal
gstExemptTaxRateIDCanada-specific field, ID of corresponding reduced tax rate, for GST-exempt customers. Must be existing and active tax rate IDInteger
*************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.
String
****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.
ZIPCodeFill 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
categoryString
stateState name.String
stateTaxRatePercentage of state sales tax.Decimal
countyCounty name.String
countyTaxRatePercentage of county sales tax.Decimal
cityCity name.String
cityTaxRatePercentage of city sales tax.Decimal
otherTaxNameNaming for custom sales tax component.String
otherTaxRatePercentage of custom sales tax component.Decimal

Response

Field nameTypeDescription
vatRateIDIntegerID of the newly-created or updated item