VAT rates

API version 1.6.0

VAT rates indicate tax amounts defined by the government that are added to products and services. Profifact provides a set of current and old VAT rates in The Netherlands. Each VAT rate has a unique ID that can be assigned to an invoice line or an offer line to indicate the VAT rate that applies. This article describe how to retrieve the set of VAT rates.
More information on the Dutch VAT rules can be found on the website of the Belastingdienst.

Index

Introduction
Retrieving all VAT rates
1. Request
2. Response

Introduction

The VAT rate model and its relations to other models

VAT rates are defined by the government and are subject to change. Instead of requiring clients of the Profifact service to keep track of the current VAT rates, Profifact provides them through the /vatrates resource. Along with the unique ID and name of each VAT rate the service returns the start and end dates of the period during which a VAT rate is valid. The start and end dates of a grace period are also returned, because VAT rates may under some conditions be used before or after the period in which they are valid. If a start or end date is not known, or not defined yet, the service returns null instead of a date.
VAT rates are identified by their unique IDs. Profifact guarantees that the unique ID of a VAT rate never changes. Clients may therefore store a local copy of the VAT rates provided by the Profifact service and use that copy instead of querying the the service. However, during validation of invoice lines and offer lines the validity of the specified VAT rates is checked. If a VAT rate is not valid (or graced) at the date of the invoice or offer, the request is denied. It is the responsibility of the client to specify valid VAT rates for all invoice lines and offer lines.
A value is provided for each VAT rate, which may be used to identify its purpose. If the value is numerical, it is the VAT percentage represented by the VAT rate. If the value is a string, the effective VAT percentage is 0 and the value gives an indication of the circumstances under which the VAT rate applies. Like unique IDs, the values of VAT rates are guaranteed to be constant even if multiple VAT rates with the same value may be valid during different periods.

Retrieving all VAT rates

Clients can retrieve all VAT rates provided by Profifact by sending an HTTP GET request to /vatrates. Authentication is required and the only additional GET parameter that can be specified is the order in which the VAT rates are returned.

Request

HTTP GET requests to /vatrates may include any of the following GET parameters:

order: A comma separated set of field names specifying the sort order of the matching items. A minus sign preceeding a field name indicates descending sort order.

Examples


            // Retrieve all VAT rates:

            GET /vatrates HTTP/1.1

            

            // Retrieve all VAT rates ordered by value:

            GET /vatrates?order=value HTTP/1.1

            

            // Retrieve all VAT rtaes order be name ascending and start date descending:

            GET /vatrates?order=name,-validFrom HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a data structure with the members defined in the table below. See the section on data types for an explanation of property data types.

Name	Type	Description
count	int	Specifies the number of items returned.
total	int	Specifies the total number of matching items.
offset	int	Specifies the offset of the first returned item in the collection of all matching items.
items	array	The array of the VAT rate objects selected for being returned based on the request.
id	int	The unique ID of the VAT rate assigned by Profifact.
name	string	The display name of the VAT rate assigned by Profifact.
value	string	The value of the VAT rate assigned by Profifact. A numeric string indicating the VAT percentage represented by the VAT rate.
validFrom	date?	Indicates the first date on which the VAT rate is valid. If the value of this property is null, the VAT rate may be considered to have no particular start date. Even though the 19% rate came into effect on january 1, 2001, it has null as its validFrom date because Profifact did not start tracking VAT rates after that date. The same is true for the 6% rate.
validTo	date?	Indicates the last date on which the VAT rate is valid. If the value of this property is null, the VAT rate may be considered to have no end date yet. For all VAT rates, the value of the validFrom property is either null or it is greater than or equal to the value of the validFrom property.
graceFrom	date?	Indicates the first date of the initial grace period of the VAT rate. The initial grace period of a VAT rate is the period during which that VAT rate is not yet valid, but may be used if particular conditions are met. The initial grace period ends at the date the VAT rate becomes valid (i.e. the value of the validFrom property). The value of this property is null if a grace period is not defined.
graceTo	date?	Indicates the last date of the concluding grace period of a VAT rate. The concluding grace period of a VAT rate is the period during which that VAT rate is no longer valid, but may still be used if particular conditions are met. The concluding grace period starts at the date the VAT rate becomes invalid (i.e. the day after the value of the validTo property). The value of this property is null if a grace period is not defined.