VAT API
A developer friendly API to help your business achieve VAT compliance
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"swagger": "2.0",
"schemes": [
"https"
],
"host": "vatapi.com",
"basePath": "/v1",
"info": {
"description": "A developer friendly API to help your business achieve VAT compliance",
"title": "VAT API",
"version": "1",
"x-apisguru-categories": [
"financial"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/http_vatapi.com_graphics_logo.svg"
},
"x-origin": [
{
"converter": {
"url": "https://github.com/lucybot/api-spec-converter",
"version": "2.7.11"
},
"format": "swagger",
"url": "https://vatapi.com/api-docs.json",
"version": "1.2"
}
],
"x-providerName": "vatapi.com"
},
"securityDefinitions": {
"apikey": {
"description": "Enter your API key",
"in": "header",
"name": "apikey",
"type": "apiKey"
}
},
"security": [
{
"apikey": []
}
],
"tags": [
{
"name": "api"
}
],
"paths": {
"/country-code-check": {
"get": {
"operationId": "country_code_check",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "The 2 digit country code",
"in": "query",
"name": "code",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Country_Code_Check"
}
}
},
"summary": "Retrieve a countries VAT rates by its 2 digit country code",
"tags": [
"api"
]
}
},
"/currency-conversion": {
"get": {
"operationId": "currency_conversion",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "The currency code you are converting from",
"in": "query",
"name": "currency_from",
"required": true,
"type": "string"
},
{
"description": "The currency code you are converting to",
"in": "query",
"name": "currency_to",
"required": true,
"type": "string"
},
{
"description": "Optional, an amount you are wanting to convert. Leave blank to just get the current rate",
"in": "query",
"name": "amount",
"required": false,
"type": "integer"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Currency_Conversion"
}
}
},
"summary": "Convert a currency",
"tags": [
"api"
]
}
},
"/invoice": {
"post": {
"operationId": "create_invoice",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "Enter invoice data as JSON",
"in": "body",
"name": "body",
"required": true,
"schema": {
"$ref": "#/definitions/Invoice_Data"
}
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Create_Invoice"
}
}
},
"summary": "Create a VAT invoice",
"tags": [
"api"
]
}
},
"/invoice/{id}": {
"delete": {
"operationId": "invoice_delete",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "Enter an invoice id",
"in": "path",
"name": "id",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "No response was specified"
}
},
"summary": "Delete an invoice",
"tags": [
"api"
]
},
"get": {
"operationId": "get_invoice",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "Enter the invoice id",
"in": "path",
"name": "id",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Retrieve_Invoice"
}
}
},
"summary": "Retrieve an invoice",
"tags": [
"api"
]
},
"put": {
"operationId": "invoice_update",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "Enter an invoice id",
"in": "path",
"name": "id",
"required": true,
"type": "integer"
},
{
"description": "Enter invoice data as JSON",
"in": "body",
"name": "body",
"required": true,
"schema": {
"$ref": "#/definitions/Update_Invoice_Array"
}
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Update_Invoice"
}
}
},
"summary": "Update an existing invoice",
"tags": [
"api"
]
}
},
"/ip-check": {
"get": {
"operationId": "ip_check",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "The IP address to search against",
"in": "query",
"name": "address",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/IP_Check"
}
}
},
"summary": "Retrieve a countries VAT rates from an IP address",
"tags": [
"api"
]
}
},
"/usage-check": {
"get": {
"operationId": "api_usage",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Api_Usage"
}
}
},
"summary": "Check api requests remaining on current subscription plan",
"tags": [
"api"
]
}
},
"/vat-number-check": {
"get": {
"description": "<p>We highly recommend if you are able, to check a VAT number on your end first to save wasted API lookups. It maybe that your customer has simply entered the wrong format. <a href='http://www.braemoor.co.uk/software/vat.shtml' target='_blank'>Heres a client side way to check the format using Javascript</a></p>",
"operationId": "vat_number_validate",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "The VAT number to validate",
"in": "query",
"name": "vatid",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified"
}
},
"summary": "Validate a VAT number",
"tags": [
"api"
]
}
},
"/vat-price": {
"get": {
"operationId": "convert_price",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
},
{
"description": "The 2 digit country code",
"in": "query",
"name": "code",
"required": true,
"type": "string"
},
{
"description": "The VAT rate to get the price for. Default: standard",
"in": "query",
"name": "country_rate",
"required": false,
"type": "string"
},
{
"description": "The price you want converting",
"in": "query",
"name": "price",
"required": true,
"type": "integer"
},
{
"description": "Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'",
"in": "query",
"name": "type",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Convert_Price"
}
}
},
"summary": "Convert a price to or from VAT price.",
"tags": [
"api"
]
}
},
"/vat-rates": {
"get": {
"operationId": "vat_rates",
"parameters": [
{
"description": "The default response type is application/json if you would like to receive an XML response then set this to XML",
"in": "header",
"name": "Response-Type",
"type": "string"
}
],
"responses": {
"200": {
"description": "No response was specified",
"schema": {
"$ref": "#/definitions/Vat_Rates"
}
}
},
"summary": "Retrieve all current EU VAT rates",
"tags": [
"api"
]
}
}
},
"definitions": {
"Api_Usage": {
"properties": {
"requests_remaining": {
"description": "The number of api requests remaining in the current billing period",
"type": "integer"
},
"requests_used": {
"description": "The number of api requests consumed within the last 30 days",
"type": "integer"
},
"status": {
"description": "Response code",
"type": "integer"
}
},
"required": [
"requests_remaining",
"requests_used",
"status"
]
},
"Convert_Price": {
"properties": {
"country_code": {
"description": "The 2 digit country code",
"type": "string"
},
"country_rate": {
"description": "The country_rate",
"type": "string"
},
"price_excl_vat": {
"description": "The price excluding VAT",
"type": "integer"
},
"price_incl_vat": {
"description": "The price including VAT",
"type": "integer"
},
"rate": {
"description": "The rate % for the country_rate",
"type": "integer"
},
"status": {
"description": "Response code",
"type": "integer"
},
"vat": {
"description": "The total amount of VAT applied",
"type": "integer"
}
},
"required": [
"country_code",
"country_rate",
"price_excl_vat",
"price_incl_vat",
"rate",
"status",
"vat"
]
},
"Country_Code_Check": {
"properties": {
"country": {
"description": "The country name",
"type": "string"
},
"country_code": {
"description": "The 2 digit country code",
"type": "string"
},
"rates": {
"$ref": "#/definitions/Country_Rates",
"description": "An array of the EU VAT rates for that country"
},
"status": {
"description": "Response code",
"type": "integer"
},
"vat_applies": {
"description": "TRUE or FALSE, depending if country is within the EU.",
"type": "string"
}
},
"required": [
"country",
"country_code",
"rates",
"status",
"vat_applies"
]
},
"Country_Data": {
"properties": {
"country": {
"description": "The country name",
"type": "string"
},
"rates": {
"$ref": "#/definitions/Country_Rates",
"description": "An array of the rates for the country"
}
},
"required": [
"country",
"rates"
]
},
"Country_Rates": {
"properties": {
"parking": {
"$ref": "#/definitions/parking",
"description": "The type of rate"
},
"reduced": {
"$ref": "#/definitions/reduced",
"description": "The type of rate"
},
"reduced_alt": {
"$ref": "#/definitions/reduced_alt",
"description": "The type of rate"
},
"standard": {
"$ref": "#/definitions/standard",
"description": "The type of rate"
},
"super_reduced": {
"$ref": "#/definitions/super_reduced",
"description": "The type of rate"
}
},
"required": [
"parking",
"reduced",
"reduced_alt",
"standard",
"super_reduced"
]
},
"Create_Invoice": {
"properties": {
"invoice": {
"$ref": "#/definitions/Invoice_Array",
"description": "The new invoice object"
},
"status": {
"description": "Response code",
"type": "integer"
}
},
"required": [
"invoice",
"status"
]
},
"Currency_Conversion": {
"properties": {
"amount_from": {
"description": "The amount you are converting from",
"type": "string"
},
"amount_to": {
"description": "The result amount you have converted to",
"type": "string"
},
"currency_from": {
"description": "The currency code you are converting from",
"type": "string"
},
"currency_to": {
"description": "The currency code you are converting to",
"type": "integer"
},
"rate": {
"description": "The rate according to HMRC at time of sale",
"type": "string"
},
"status": {
"description": "Response code",
"type": "integer"
}
},
"required": [
"currency_from",
"currency_to",
"rate",
"status"
]
},
"IP_Check": {
"properties": {
"country": {
"description": "The country name",
"type": "string"
},
"country_code": {
"description": "The 2 digit country code",
"type": "string"
},
"rates": {
"$ref": "#/definitions/Country_Rates",
"description": "An array of the EU VAT rates for that country"
},
"status": {
"description": "Response code",
"type": "integer"
},
"vat_applies": {
"description": "TRUE or FALSE, depending if country is within the EU.",
"type": "string"
}
},
"required": [
"country",
"country_code",
"rates",
"status",
"vat_applies"
]
},
"Invoice_Array": {
"properties": {
"business_address": {
"description": "Your business address",
"type": "string"
},
"business_name": {
"description": "Your business name",
"type": "string"
},
"conversion_rate": {
"description": "The rate of conversion at time of supply",
"type": "integer"
},
"currency_code": {
"description": "3 character currency code for invoice",
"type": "string"
},
"currency_code_conversion": {
"description": "3 character currency code to be converted from original transaction currency",
"type": "string"
},
"customer_address": {
"description": "Your customers address",
"type": "string"
},
"customer_name": {
"description": "Your customers name or trading name",
"type": "string"
},
"customer_vat_number": {
"description": "Customers VAT number",
"type": "string"
},
"date": {
"description": "The date the invoice was issued",
"type": "string"
},
"discount_rate": {
"description": "The discount rate per item",
"type": "integer"
},
"discount_total": {
"description": "Total amount of discount",
"type": "integer"
},
"invoice_number": {
"description": "A sequential invoice number",
"type": "integer"
},
"invoice_url": {
"description": "A perminant URL to your VAT invoice",
"type": "string"
},
"items": {
"description": "An array of your invoice items",
"items": {
"$ref": "#/definitions/Invoice_Items"
},
"type": "array"
},
"logo_url": {
"description": "A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended",
"type": "string"
},
"notes": {
"description": "Any notes attached to the invoice",
"type": "string"
},
"subtotal": {
"description": "Total amount excluding VAT",
"type": "integer"
},
"tax_point": {
"description": "(or 'time of supply') if this is different from the invoice date",
"type": "string"
},
"total": {
"description": "Total amount of including VAT",
"type": "integer"
},
"type": {
"description": "The type of invoice. Either 'sale' or 'refund'",
"type": "string"
},
"vat_number": {
"description": "Your VAT number",
"type": "string"
},
"vat_total": {
"description": "Total amount of VAT",
"type": "integer"
}
},
"required": [
"business_address",
"business_name",
"currency_code",
"date",
"discount_total",
"invoice_number",
"invoice_url",
"items",
"subtotal",
"tax_point",
"total",
"type",
"vat_number",
"vat_total"
]
},
"Invoice_Data": {
"properties": {
"business_address": {
"description": "Your business address",
"type": "string"
},
"business_name": {
"description": "Your business name",
"type": "string"
},
"conversion_rate": {
"description": "The rate of conversion at time of supply",
"type": "integer"
},
"currency_code": {
"description": "3 character currency code for invoice",
"type": "string"
},
"currency_code_conversion": {
"description": "3 character currency code to be converted from original transaction currency",
"type": "string"
},
"customer_address": {
"description": "Your customers address",
"type": "string"
},
"customer_name": {
"description": "Your customers name or trading name",
"type": "string"
},
"customer_vat_number": {
"description": "Optional customers VAT number",
"type": "string"
},
"date": {
"description": "The date the invoice was issued",
"type": "string"
},
"discount_rate": {
"description": "The discount rate per item",
"type": "string"
},
"items": {
"description": "An array of your invoice items",
"items": {
"$ref": "#/definitions/Invoice_Items"
},
"type": "array"
},
"notes": {
"description": "Add a note to the invoice.",
"type": "string"
},
"price_type": {
"description": "Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'",
"type": "string"
},
"tax_point": {
"description": "(or 'time of supply') if this is different from the invoice date",
"type": "string"
},
"type": {
"description": "The type of invoice. Either 'sale' or 'refund'",
"type": "string"
},
"vat_number": {
"description": "Your VAT number",
"type": "string"
},
"zero_rated": {
"description": "To Zero-Rate the VAT, set to true.",
"type": "string"
}
},
"required": [
"business_address",
"business_name",
"currency_code",
"items",
"type",
"vat_number"
]
},
"Invoice_Items": {
"properties": {
"description": {
"description": "The item line description",
"type": "string"
},
"price_each": {
"description": "The price of the individual item (Ex VAT)",
"type": "integer"
},
"quantity": {
"description": "The quantity of the item",
"type": "integer"
},
"vat_rate": {
"description": "The VAT rate at which the item is charged",
"type": "integer"
}
},
"required": [
"description",
"price_each",
"quantity",
"vat_rate"
]
},
"Retrieve_Invoice": {
"properties": {
"invoice": {
"$ref": "#/definitions/Retrieve_Invoice_Array",
"description": "The invoice array"
},
"status": {
"description": "Response code",
"type": "string"
}
},
"required": [
"invoice",
"status"
]
},
"Retrieve_Invoice_Array": {
"properties": {
"business_address": {
"description": "Your business address",
"type": "string"
},
"business_name": {
"description": "Your business name",
"type": "string"
},
"conversion_rate": {
"description": "The rate of conversion at time of supply",
"type": "integer"
},
"currency_code": {
"description": "3 character currency code for invoice",
"type": "string"
},
"currency_code_conversion": {
"description": "3 character currency code to be converted from original transaction currency",
"type": "string"
},
"customer_address": {
"description": "Your customers address",
"type": "string"
},
"customer_name": {
"description": "Your customers name or trading name",
"type": "string"
},
"customer_vat_number": {
"description": "Optional, customers VAT number",
"type": "string"
},
"date": {
"description": "The date the invoice was issued",
"type": "string"
},
"discount_rate": {
"description": "The discount rate per item",
"type": "integer"
},
"discount_total": {
"description": "Total amount of discount",
"type": "integer"
},
"id": {
"description": "The invoice ID",
"type": "integer"
},
"invoice_url": {
"description": "A perminant URL to your VAT invoice",
"type": "string"
},
"items": {
"description": "An array of your invoice items",
"items": {
"$ref": "#/definitions/Invoice_Items"
},
"type": "array"
},
"logo_url": {
"description": "A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended",
"type": "string"
},
"notes": {
"description": "Any notes attached to the invoice",
"type": "string"
},
"price_type": {
"description": "Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'",
"type": "string"
},
"subtotal": {
"description": "Total amount excluding VAT",
"type": "integer"
},
"tax_point": {
"description": "(or 'time of supply') if this is different from the invoice date",
"type": "string"
},
"total": {
"description": "Total amount of including VAT",
"type": "integer"
},
"type": {
"description": "The type of invoice. Either 'sale' or 'refund'",
"type": "string"
},
"vat_number": {
"description": "Your VAT number",
"type": "string"
},
"vat_total": {
"description": "Total amount of VAT",
"type": "integer"
},
"zero_rated": {
"description": "To Zero-Rate the VAT, set to true.",
"type": "string"
}
},
"required": [
"business_address",
"business_name",
"currency_code",
"date",
"discount_total",
"id",
"invoice_url",
"items",
"subtotal",
"tax_point",
"total",
"type",
"vat_number",
"vat_total"
]
},
"Update_Invoice": {
"properties": {
"invoice": {
"$ref": "#/definitions/Retrieve_Invoice_Array",
"description": "The invoice array"
},
"status": {
"description": "Response code",
"type": "string"
}
},
"required": [
"invoice",
"status"
]
},
"Update_Invoice_Array": {
"properties": {
"business_address": {
"description": "Your business address",
"type": "string"
},
"business_name": {
"description": "Your business name",
"type": "string"
},
"conversion_rate": {
"description": "The rate of conversion at time of supply",
"type": "integer"
},
"currency_code": {
"description": "3 character currency code for invoice",
"type": "string"
},
"currency_code_conversion": {
"description": "3 character currency code to be converted from original transaction currency",
"type": "string"
},
"customer_address": {
"description": "Your customers address",
"type": "string"
},
"customer_name": {
"description": "Your customers name or trading name",
"type": "string"
},
"customervat_number": {
"description": "Customers VAT number",
"type": "string"
},
"date": {
"description": "The date the invoice was issued",
"type": "string"
},
"discount_rate": {
"description": "The discount rate per item",
"type": "string"
},
"items": {
"description": "An array of your invoice items",
"items": {
"$ref": "#/definitions/Invoice_Items"
},
"type": "array"
},
"logo_url": {
"description": "A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended",
"type": "string"
},
"notes": {
"description": "Add a note to the invoice.",
"type": "string"
},
"tax_point": {
"description": "(or 'time of supply') if this is different from the invoice date",
"type": "string"
},
"type": {
"description": "The type of invoice. Either 'sale' or 'refund'",
"type": "string"
},
"vat_number": {
"description": "Your VAT number",
"type": "string"
}
},
"required": [
"business_address",
"business_name",
"currency_code",
"customervat_number",
"items",
"type"
]
},
"Vat_Rates": {
"properties": {
"countries": {
"description": "An array of the EU VAT countries and their respective rates",
"items": {
"$ref": "#/definitions/Vat_Rates_Countries"
},
"type": "array"
},
"status": {
"description": "Response code",
"type": "integer"
}
},
"required": [
"countries",
"status"
]
},
"Vat_Rates_Countries": {
"properties": {
"country_code": {
"$ref": "#/definitions/Country_Data",
"description": "The 2 digit country code"
}
},
"required": [
"country_code"
]
},
"parking": {
"properties": {
"applies_to": {
"description": "The type of goods the rate applies to",
"type": "string"
},
"value": {
"description": "The % VAT rate",
"type": "integer"
}
},
"required": [
"applies_to",
"value"
]
},
"reduced": {
"properties": {
"applies_to": {
"description": "The type of goods the rate applies to",
"type": "string"
},
"value": {
"description": "The % VAT rate",
"type": "integer"
}
},
"required": [
"applies_to",
"value"
]
},
"reduced_alt": {
"properties": {
"applies_to": {
"description": "The type of goods the rate applies to",
"type": "string"
},
"value": {
"description": "The % VAT rate",
"type": "integer"
}
},
"required": [
"applies_to",
"value"
]
},
"standard": {
"properties": {
"value": {
"description": "The % VAT rate",
"type": "integer"
}
},
"required": [
"value"
]
},
"super_reduced": {
"properties": {
"applies_to": {
"description": "The type of goods the rate applies to",
"type": "string"
},
"value": {
"description": "The % VAT rate",
"type": "integer"
}
},
"required": [
"applies_to",
"value"
]
}
}
}