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 numbers 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 number 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 eperiodical.
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"
}

Batches

Rates

Last updated 3 months ago

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 numbers 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.

Quotes

The Quote Object

postCreate a quote

getList all quotes

getRetrieve a quote

post
Create a quote

get
List all quotes

get
Retrieve a quote