Custom Connector
Vatlayer Connector
EU
The Vatlayer Connector provides access to VAT number validation, EU VAT rates retrieval, and price calculations for EU member states. It acts as a proxy supporting VAT number validation, single-country VAT rates, all EU VAT rates, VAT-compliant price calculations, and reduced VAT rate types.
Overview
Integration Overview
This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the Vatlayer Connector.
- validateVatNumber. Validates a VAT number and retrieves associated company information.
- getVatRate. Retrieves VAT rates for a specified EU member state.
- getAllVatRates. Retrieves VAT rates for all 28 EU member states.
- calculateVatPrice. Calculates a VAT-compliant price based on a provided amount and country.
- getVatTypes. Retrieves a list of available reduced VAT rate types.
Documentation
Detailed Integration Documentation
VAT Number Validation
| Action | validateVatNumber |
|---|---|
| Purpose | Validates a provided VAT number and returns company information (name and address) for financial or compliance purposes. |
| Parameters | Required: access_key, vat_number (e.g. LU26375245). Optional: format (1 for JSON), callback (JSONP). |
| Configuration | Configure the connector with the Vatlayer base URL and API key. |
| Output | Successful: JSON with valid, database, format_valid, query, country_code, vat_number, company_name, company_address. Failure: error object (e.g. invalid_access_key). |
| Workflow example | Execute validateVatNumber with access_key and vat_number, then use the company details for compliance checks or customer validation. |
Single Country VAT Rates Retrieval
| Action | getVatRate |
|---|---|
| Purpose | Retrieves VAT rates for a specified EU member state, including standard and reduced rates, by country code or IP. |
| Parameters | Required: access_key, country_code (e.g. DE). Optional: ip_address, use_client_ip (1), format, callback. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON with success, country_code, country_name, standard_rate, reduced_rates. Failure: error object (invalid_access_key). |
| Workflow example | Execute getVatRate with country_code=DE, then use standard/reduced rates for pricing or tax calculations. |
All EU VAT Rates Retrieval
| Action | getAllVatRates |
|---|---|
| Purpose | Retrieves VAT rates for all 28 EU member states — a comprehensive dataset for multi-country tax calculations. |
| Parameters | Required: access_key. Optional: format, callback. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON with success and a rates array (country_code, country_name, standard_rate, reduced_rates). Failure: error object (invalid_access_key). |
| Workflow example | Execute getAllVatRates, then use the data for cross-country tax analysis or e-commerce. |
VAT Compliant Price Calculation
| Action | calculateVatPrice |
|---|---|
| Purpose | Calculates a VAT-compliant price based on a provided amount and country, accounting for standard or reduced VAT rates. |
| Parameters | Required: access_key, amount (e.g. 100), country_code (e.g. GB). Optional: ip_address, use_client_ip, type (e.g. medical), incl (1 if amount includes VAT), format, callback. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON with success, country_code, country_name, price_excl_vat, price_incl_vat, vat_rate, type. Failure: error object (invalid_access_key). |
| Workflow example | Execute calculateVatPrice with amount=100 and country_code=GB, then use the prices for checkout or invoicing. |
Reduced VAT Rate Types Retrieval
| Action | getVatTypes |
|---|---|
| Purpose | Retrieves a list of available reduced VAT rate types, so applications can apply appropriate rates for specific goods. |
| Parameters | Required: access_key. Optional: format, callback. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON with success and a types array (e.g. [foodstuffs, books, medical]). Failure: error object (invalid_access_key). |
| Workflow example | Execute getVatTypes, then use the types to configure pricing rules for specific goods. |
Example Workflow: VAT Validation and Price Calculation
| Validate VAT number | Use validateVatNumber with vat_number to verify a customer’s VAT number and retrieve company details. |
|---|---|
| Retrieve VAT rates | Execute getVatRate with country_code=DE, or getAllVatRates for all EU countries. |
| Calculate price | Execute calculateVatPrice with amount, country_code, and optionally type=medical for checkout or invoicing. |
| Configure reduced rates | Execute getVatTypes and apply the appropriate type in subsequent calculateVatPrice calls. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.