Repository files navigation

Some countries requires businesses to apply, for any sales of online/electronic/digital/cloud services toconsumers (B2C), avalue-added tax(VAT) on all purchases made by their citizen. This impose all foreign companies to track theresidency of all their customers, to apply the right tax.

This trend started January 1st 2015 with all European country, and is about to beimplemented by others too.

As the rate depends on the locality of the customer, this project aims to centralize,in a machine-readable format (currently aplain CSV file), the list of applicable rates for each country ofresidence, and all their territorial exceptions.

This is a painful job, worth sharing with a community, so please help me keep this database up to date! :)

I'm impressed with your BFPO detail.--Tim Whitlock

I'm glad to see independently researched data confirming mine!--Will Bond

All B2C customers matching the locality in that file are subject to the corresponding tax.

Your B2B customers are exempted of VAT, as long as they provide aregistered VAT number. You can check their validity on theVAT InformationExchange System (VIES). Irecommend using a third-party library to automate the process, likepyvat for Python. A B2B customer without VATnumber is considered as a simple B2C customer, so local rate applies.

Note that starting January 1st, 2015, theserules applies to all non-European SaaSbusinesseswith European customers.

This matrix expose the current completeness of the database:

start_date is an inclusiveISO 8601 calendardate from which the ratestarts to apply.

stop_date is an inclusiveISO 8601 calendardate from which the rate isno longer valid.

territory_codes is a list of (eventually mixed):

• ISO 3166-1 alpha-2 countrycodes,
• European Commission countrycodes,
• ISO 3166-2 subdivision codes,
• normalized postalcode with aleading ISO 3166-1 alpha-2 country codes.

currency_code is thede jureISO 4217 currency code (a.k.a.legal tender), notde facto's one.

rate is the decimal rate.

rate_type is the kind of rate. Either:

• standard
• increased
• reduced
• parking

description human-readable description of the territory the rate applies to,and eventual rationale behind the application.

Rows are sorted byterritory_codes, thenstart_date.

Starting from this database, your next step is to interpret the data.

By looking at the dates, you can compute if a rate is either current,historical or future. Beware, some rates changes in the middle of a month.That means on theory, your billing system should support pro-rata applicationof several rates on a monthly invoice.

To choose the right rate, you then need to guess the location of your customer.I advise you to derive this data from the billing address, as it's the mostcommon element with the necessary administrative granularity. An address thatis properly normalized is precise enough, down to the postal code, to selectthe right VAT rule, including territorial exceptions. To solve the territorycomplex, I wrote aPython module to parse and normalize postaladdresses.

The process of building up this database is somewhat fuzzy.

This database is unequivocally founded on the latestofficial VATRatesdocument from the EC portal. It provides all member states' rates and theirhistorical values. You'll also find there a description of regions andterritories where special or no VAT rates applies.

Still, the hardest part of establishing this database lies in thecharacterization of locality. Member states and some regions are easy: theyhave a dedicated country code. For these we rely onISO 3166-1alpha-2, with an extra compatibilitylayer forEuropean Commission countrycodes (i.e. theGB/UKandGR/EL pairs).

When this is not enough, we go down to a lower administrative level andleverage subdivision codes fromISO3166-2.

Things get messy once VAT rules only applies to areas as small as a town. Inwhich case I guesstimated the geographic zone with postal codes fetched fromindividual Wikipedia pages.

Finally, for completeness, I compiled the catalog ofmember's states specialterritoriesand restarted the locality characterization process for these. I was able toadd the missing entries based on the list of included and excluded zones of theEU VAT area.

• officialdocumentation
• List of electronically supplied services
• Rachel Andrew's micro-site
• Awesome Billing and Payments - 💰 Billing & Payments Knowledge Base for Cloud Providers.

I decided to create this database because all thecurrent VAT libs were quitenaiveabout the territory definition. Most of the time it's only based on thecountry, while the territory a tax applies to, in a fiscal context, is a muchmore insidious concept carrying administrative, political and historicalweight.

To match the place the supply takes place against the VAT database, I created aPython module to normalize and parse postaladdressed of my customers.

The content of this repository is licensed under aBSD 2-ClauseLicense.