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 at checkout. Once your visitor checks out, you can use the object’s unique identifier 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 applications anymore. You can generate as many quotes as you like.

Preventing abuse: 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 visitors get hold of your API access key, they can create new quote objects themselves.

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.
vat.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.
vat.rate VAT rate applied for the calculation. If member_state is false, the value will be 0.
vat.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 with the validation body parameter in the POST request. Defaults to null. See validation object for reference.

Create a quote

Creates a quote object.

Request

curl -X POST https://api.vatstack.com/v1/quotes \
     -H "Authorization: Credential 8637070eccf71b29f0e859f1bd5d9257" \

Body Parameters

Parameter Description
vat_inclusive optional Boolean for whether the resulting VAT amount should be calculated inclusive or exclusive of VAT. Defaults to false.
amount required Amount in cents (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
validation optional 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 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 2-letter ISO country code. If provided, the ip_address parameter will be ignored.
category optional Digital products category used for calculation. Supports audiobook, ebook and eperiodical.

Response

Quote object successfully created. Example includes a populated validation object.

{
  "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"
}

List All Quotes

Retrieves all quote objects in order of creation, with the most recent appearing highest.

Request

curl -X GET https://api.vatstack.com/v1/quotes \
     -H "Authorization: Credential 8637070eccf71b29f0e859f1bd5d9257" \

Query Parameters

Parameter Description
limit optional Limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
page optional Integer for the current page.

Response

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"
    },
    ...
  ]
}

Retrieve a Quote

Retrieves a quote object by the :id path parameter.

Request

curl -X GET https://api.vatstack.com/v1/quotes/:id \
     -H "Authorization: Credential 8637070eccf71b29f0e859f1bd5d9257" \

Response

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"
}