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 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    
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    
code  Corresponding VAT code in accounting software  String    
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    
gstExemptTaxRateID  Canada-specific field, ID of corresponding reduced tax rate, for GST-exempt customers. 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. 
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.
 
   
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    

Response

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