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.
Retrieving all VAT rates
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 ratesClients 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.
RequestHTTP GET requests to /vatrates may include any of the following GET parameters:
- 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.
// 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
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.
|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.|
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
|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.|