Quotes

Correct VAT treatment between you and your customer for every sale using your existing business information. Interchange cached checkout data between the frontend and backend applications.

The quote object combines the best of the rate object and validation object and takes them a step further. It uses your existing business information to perform the entire VAT-compliant business logic for you. All VAT rules have been centralized so that every response is directly actionable.

Our core resources for rates and validations are “cold” fetches because they are provided as is and you still have to research tax regulations that specifically apply to each sale. We consider responses from the quotes endpoints as “warm” fetches because they are dynamically adapted to the circumstances between your business and your customer.

For example, if your business is situated in Italy and your customer is also in Italy, the quoted price will always include a VAT because VAT is always charged when transactions occur within the same EU member state (even for business customers). The reverse-charge mechanism does not apply here. This is a tax rule that you would have had to implement yourself, but is now taken care of.

The ideal way to use the quote object is to generate a new one whenever your visitor loads the checkout window in your frontend application. When your visitor does check out, you can pass the object’s unique identifier to your backend application for retrieval. You should therefore cache the object’s ID in your frontend application.

This interchanging of data allows you to charge the exact same amount that your visitor has been presented with earlier. You don’t have to replicate the same business logic in the frontend and the backend anymore.

If you generate quote objects from your frontend application, you should perform logical tests of the object’s content before you proceed with the actual charge to prevent abuse. For example, compare the object’s amount with your product’s price. If a visitor gets hold of your API access key, she can create new quote objects herself.

The Quote Object

Key

Description

id

Unique identifier for the object.

abbreviation

Abbreviation of local_name.

amount

Amount in cents, as given in your request.

amount_total

Total amount to be charged in consideration of the vat.inclusive boolean. This is the amount you should display to customers.

category

Category of the digital product. Defaults to null if no category was specified in the request or if the category cannot be applied for the country_code.

country_code

2-letter ISO country code. Note that while Greek VAT IDs contain the EL country code, our response will return the ISO country code GR.

country_name

Corresponding English name of country_code.

created

ISO date at which the object was created.

ip_address

The same IP address coming from the ip_address body parameters, or the geolocated IP address if none was provided. Value is null if country_code was provided.

local_name

Localized name of the VAT.

member_state

Boolean indicating whether the country is an EU member state.

vat

amount

VAT amount in cents.

inclusive

Specifies if the given amount is inclusive (common for EU consumers) or exclusive of VAT. This affects how the vat.amount is calculated. If false, you should present amount plus vat.amount to your customer as the final price to pay.

rate

VAT rate applied for the calculation. If member_state is false, the value will be 0.

rate_type

Automatically determined type of VAT rate based on inputs. Can be null, exempt, reduced, reverse_charge, standard or zero.

updated

ISO date at which the object was updated.

validation

Populated validation object if an ID is attached. You can attach a validation object either with the vat_id or the validation body parameter in the POST request. Defaults to null. See validation object for reference.

post
Create a quote

https://api.vatstack.com/v1/quotes
Creates a quote object.
Request
Response
Request
Body Parameters
vat_inclusive
optional
boolean
Whether the resulting VAT amount should be calculated inclusive or exclusive of VAT. Defaults to false.
amount
required
number
Amount in cents (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
validation
optional
string
Unique identifier of a validation object. This is useful if you let your customer enter a VAT ID beforehand. Its valid value can affect vat.amount, vat.rate and amount_total when zero-rating.
ip_address
optional
string
IP address to geolocate the VAT rate for. If neither IP address nor country_code is provided, it will be automatically determined from the request.
country_code
optional
string
2-letter ISO country code. If provided, the ip_address parameter will be ignored.
category
optional
string
Digital products category used for calculation. Supports audiobook,ebook and periodical.
Response
201: Created
Quote object successfully created.
{
"id": "5dc490ea73c1ce2f69628900",
"abbreviation": "ALV nro",
"amount": 10000,
"amount_total": 10000,
"category": null,
"country_code": "IE",
"country_name": "Ireland",
"ip_address": "92.251.255.11",
"local_name": "Arvonlisäveronumero",
"member_state": true,
"validation": {
"id": "5dc490ea73c1ce2f69628901",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW5H1hUQb",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-11-07T00:00:00.000Z",
"created": "2019-11-07T21:47:22.952Z",
"updated": "2019-11-07T21:47:22.952Z"
},
"vat": {
"amount": 0,
"inclusive": false,
"rate": 0,
"rate_type": "reverse_charge"
},
"created": "2019-11-07T21:47:22.955Z",
"updated": "2019-11-07T21:47:22.955Z"
}

get
List all quotes

https://api.vatstack.com/v1/quotes
Retrieves all quote objects in order of creation, with the most recent appearing highest.
Request
Response
Request
Query Parameters
limit
optional
number
Limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
page
optional
number
Integer for the current page.
Response
200: OK
Quote objects successfully retrieved.
{
"has_more": true,
"quotes_count": 23,
"quotes": [
{
"id": "5dc490ea73c1ce2f69628900",
"abbreviation": "ALV nro",
"amount": 10000,
"amount_total": 10000,
"category": null,
"country_code": "IE",
"country_name": "Ireland",
"ip_address": "92.251.255.11",
"local_name": "Arvonlisäveronumero",
"member_state": true,
"validation": {
"id": "5dc490ea73c1ce2f69628901",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW5H1hUQb",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-11-07T00:00:00.000Z",
"created": "2019-11-07T21:47:22.952Z",
"updated": "2019-11-07T21:47:22.952Z"
},
"vat": {
"amount": 0,
"inclusive": false,
"rate": 0,
"rate_type": "reverse_charge"
},
"created": "2019-11-07T21:47:22.955Z",
"updated": "2019-11-07T21:47:22.955Z"
},
...
]
}

get
Retrieve a quote

https://api.vatstack.com/v1/quotes/:id
Retrieves a quote object.
Request
Response
Request
Path Parameters
id
required
string
Identifier of the quote object to be retrieved.
Response
200: OK
Quote object successfully retrieved.
{
"id": "5dc490ea73c1ce2f69628900",
"abbreviation": "ALV nro",
"amount": 10000,
"amount_total": 10000,
"category": null,
"country_code": "IE",
"country_name": "Ireland",
"ip_address": "92.251.255.11",
"local_name": "Arvonlisäveronumero",
"member_state": true,
"validation": {
"id": "5dc490ea73c1ce2f69628901",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW5H1hUQb",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-11-07T00:00:00.000Z",
"created": "2019-11-07T21:47:22.952Z",
"updated": "2019-11-07T21:47:22.952Z"
},
"vat": {
"amount": 0,
"inclusive": false,
"rate": 0,
"rate_type": "reverse_charge"
},
"created": "2019-11-07T21:47:22.955Z",
"updated": "2019-11-07T21:47:22.955Z"
}