VAT

Make sure you familiarize yourself with the other important concepts of our API:
Products and Articles, Sync Markers
After taking the time to understand these concepts, you will much better understand the basics of our API.

Introduction

VAT (Value-added tax) is an inescapable subject when it comes to sales. It specifies an additional percentage that is charged to the buyer for services or products provided. The seller is responsible for paying this tax. Of course, MplusKASSA support VAT and provides various ways of setting the percentages and changing which VAT percentages are charged and how they are displayed.

Contents

New rules for e-commerce starting 1 july 2021

As of 1 july 2021, webshops selling from or to the EU must adhere to the new VAT guidelines. This may mean you have to charge the VAT rates of another country than the one your shop is based in. There are two ways to do this with the MplusKASSA API:

1. Use the VAT per line feature to override the VAT percentage for each line in your orders/invoices.

2. When saving the order/invoice, specify the ISO 3166-1 alpha-3 country code of the country you are shipping to, through the property vatCountryIso3.
Added in API v37.0.0

Don’t forget to configure the VAT rates for these countries within the MplusKASSA software too! (Beheer > Financieel > BTW percentages)

Below you will find a partial example of an order that will be calculated based on VAT rates for the United Kingdom ( GBR).

» » » Request » » »

XHTML
1
2
3
4
5
6
7
8
9
10
...
<ns:order>
  ...
  <ns:lineList>
    ..
  </ns:lineList>
  <ns:vatCountryIso3>GBR</ns:vatCountryIso3>
  ...
</ns:order>
...

VAT codes, percentages and method

The VAT code ( vatCode in the API) is a code that specificies which VAT category an article belongs to. MplusKASSA provides 5 VAT codes for you to configure. The Netherlands has 2 VAT categories, 6% VAT and 21% VAT. In MplusKASSA, those are mapped to VAT code 1 (6%) and VAT code 2 (21%). Other countries may have different VAT percentages, which may be mapped to different VAT codes. To retrieve the VAT mapping of the administration you are working with, you can use the API function getVatGroupList().

The VAT percentage ( vatPercentage in the API) is the actual percentage of VAT that is applied to the article. It is always expressed in 1/100th of a percent. E.g. 21% is expressed as 2100.

The VAT method ( vatMethod in the API) is a property of an invoice or order, that specifies if the VAT should be specified (a) inclusive ( VAT-METHOD-INCLUSIVE), (b) exclusive ( VAT-METHOD-EXCLUSIVE) or (c) shifted ( VAT-METHOD-SHIFTED). Inclusive is usually reserved for business-to-customer transactions, exclusive is generally for business-to-business and shifted is for situations where the VAT is paid by the buyer. For instance, this often happens with international transactions.

getVatGroupList Retrieve the configured VAT percentages

« « « Response « « «

XHTML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="urn:mplusqapi" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns:getVatGroupListResponse>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>0</ns:vatCode>
        <ns:vatPercentage>0</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>1</ns:vatCode>
        <ns:vatPercentage>600</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>2</ns:vatCode>
        <ns:vatPercentage>2100</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>3</ns:vatCode>
        <ns:vatPercentage>0</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>4</ns:vatCode>
        <ns:vatPercentage>0</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>1</ns:branchNumber>
        <ns:vatCode>5</ns:vatCode>
        <ns:vatPercentage>0</ns:vatPercentage>
      </ns:vatGroup>
      <ns:vatGroup>
        <ns:branchNumber>2</ns:branchNumber>
        <ns:vatCode>0</ns:vatCode>
        <ns:vatPercentage>0</ns:vatPercentage>
      </ns:vatGroup>
    </ns:getVatGroupListResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

getProducts VAT per article

When you request article details through getProducts, you receive the vatCode and related vatPercentage of the article.

« « « Response « « «

XHTML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="urn:mplusqapi" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns:GetProductsResponse>
      <ns:productList>
        <ns:product>
          <ns:productNumber>1234</ns:productNumber>
          <ns:description>Brood volkoren</ns:description>
          <ns:articleList>
            <ns:article>
              <ns:articleNumber>1234</ns:articleNumber>
              <ns:description>Brood volkoren</ns:description>
              <ns:vatCode>1</ns:vatCode>
              <ns:vatPercentage>600</ns:vatPercentage>
            </ns:article>
          </ns:articleList>
        </ns:product>
      </ns:productList>
    </ns:GetProductsResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

VAT per line

VAT codes and percentages can be overruled on a per-line basis. That means that you can add an article to an order or invoice, but have it use a separate VAT code and even a separate VAT percentage from the default configuration.

» » » Request » » »

XHTML
1
2
3
4
5
6
7
8
9
10
11
12
...
<ns:lineList>
  <ns:line>
    <ns:articleNumber>1234</ns:articleNumber>
    <ns:text>Brood volkoren</ns:text>
    <ns:data>
      <ns:vatCode>4</ns:vatCode>
      <ns:vatPercentage>900</ns:vatCode>
    </ns:data>
  </ns:line>
</ns:lineList>
...