The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Tax Location Validation

Australia, the European Union and New Zealand all require two pieces of evidence proving the country of the customer before tax can be collected on a digital services sale to a consumer. Recurly's Tax Location Validation automates this compliance for your business.

Supported Regions

With the growth of cross-border tax laws on digital services, more countries are adopting regulation on collecting two pieces of location evidence when applying tax. Recurly currently has a Location Validation option for these tax regions:

  • Australia
  • European Union (including United Kingdom until 12/31/2021)
  • New Zealand
  • United Kingdom (available starting 1/1/2021)

How Tax Location Validation Works

While location evidence is needed for posting an invoice, Recurly runs the tax location validation at the time the account's taxable address is added to, or updated on, the account. Then at the time of invoicing, Recurly checks the status of the account and allows the invoice to be posted if the account is valid and blocks the invoice if the account is invalid.

The account's taxable address is determined by the Tax Calculation Address setting to "Use Account Info Address on all Invoices", found on the Tax Settings page under Configuration > Taxes > Tax Settings.

  • If disabled, the taxable address is the Billing Address
  • If enabled, the taxable address is the Account Address

NOTE: Manual collection invoices will only use the Account Address, but are not supported in Tax Location Validation. See details below under "Manual Invoices Not Supported".

Tax location validation will trigger for any taxable address update where the country is in the enabled validation region, either Australia, the European Union, or New Zealand, and the address does not include a VAT number (for Australia, the VAT number can have a value, but it must not be qualified for an exemption). The validation will check for one additional piece of matching country evidence against the taxable address's country. If a match cannot be found, the validation will fail and give the account a status of invalid. A failed validation will not block the address update.

If the account's taxable address is the Billing Address, these three fields will be checked for a country that matches the Billing Address country:

  1. Account Address Country
  2. IP Address Country
  3. Credit Card BIN Country

If the account's taxable address is the Account Address, these three fields will be checked for a country that matches the Account Address country:

  1. Billing Address Country
  2. IP Address Country
  3. Credit Card BIN Country

Billing Address

You can use the Billing Address as the taxable address or a secondary piece of evidence if you are collecting a credit card, PayPal, or Amazon.

  • PayPal will provide the customer's country when signup is through Recurly's Hosted Payment Pages.
  • If the PayPal signup is through Recurly.js, you will need to collect country from the customer separately and send a second "Update Billing Info" API call to store the country before the subscription is created.

Account Address

You can use the Account Address as the taxable address or a secondary piece of evidence by using it to store the customer's shipping or mailing address.

  • Pay with Amazon has the option to copy the returned address into the Account Address.

IP Address

You can use the Billing Information's IP Address as a secondary piece of evidence if you are collecting a credit card, PayPal, or Amazon. Recurly collects and stores the customer's IP address whenever they use a Hosted Page (Hosted Payment Pages or Hosted Account Management) for adding or updating Billing Information, or for actions through Recurly.js. You can set your own collected IP address through the Billing Info API.

  • As location validation based on IP Address is not always accurate, it is recommended to collect both Billing Address and Account Address from the customer when Credit Card BIN will not be available (for example, when using PayPal or Amazon).

Credit Card BIN

You can use the Billing Information's Credit Card BIN as a secondary piece of evidence if you are collecting a credit card from the customer. The BIN is the id for the credit card's bank. Recurly extracts the bank's country through a BIN lookup. The country of a customer's bank usually matches the customer's billing address country. In most cases where they do not match, it is a case of fraud. Credit card BIN country will be looked up whenever Location Validation is run. The BIN and the country returned will be shown on the Billing Info of the account as a field called "BIN".

  • PayPal and Amazon do not support BIN country lookup because Recurly does not have access to the credit card number.

Enable Tax Location Validation

To enable Tax Location Validation for Australia, the European Union or New Zealand, go to the Tax Settings page in your Admin Console under Configuration > Taxes > Tax Settings.

To validate the location of Australian customers, enable "GST Location Validation" under "Australia Settings".

To validate the location of European Union customers, enable "VAT Location Validation" under "European Union VAT Settings".

To validate the location of New Zealand customers, enable "GST Location Validation" under "New Zealand Settings".

When you enable the Tax Location Validation feature, we will run a validation on all accounts that:

  • Have a taxable address in the region you are enabling: Australia, European Union or New Zealand
  • Do not have a VAT Number or GST Number on that taxable address (For Australia, no exemption qualified ABN)
  • Currently have an active or future subscription

If you change the "Tax Calculation Address" on the Tax Settings page by either enabling or disabling the "Use Account Info Address on all Invoices", Recurly will re-validate all of your accounts fitting the above criteria, but with the opposite address as the taxable address for the account.

When tax location validation is run on your existing accounts, Recurly will email your Billing Contact email address for each account that returns invalid.

Identify Valid and Invalid Accounts

An account's validation status can be determined in the following ways:

Email to Billing Contact

Whenever an address update changes an account's status to invalid, Recurly will email your Billing Contact email address with the account code of the invalid account. You will need to work with the customer to add a second piece of location evidence to the account or their current subscription will expire at renewal.

VAT Location Validation

VAT Location Validation

GST Location Validation

GST Location Validation

Accounts Export

If Australia, European Union or New Zealand tax location validation is enabled on our site, the Accounts export will include two additional columns that will tell you whether the account has been validated and what it's current status is.

View documentation on the full Accounts export here.

Name
Example
Description

tax_location_valid

TRUE, FALSE

Indicates if account passed tax location validation. This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled.

location_validation_tax_type

eu, nz

The region of the tax location validation run on the account. eu references the European Union VAT Location Validation. nz references the New Zealand GST Location Validation. This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled.

Admin Console

Invalid accounts will display a red banner across the top of the account page alerting you to the invalid status. This banner will not show on the Hosted Account Management page.

VAT Location Validation

VAT Location Validation

GST Location Validation

GST Location Validation

Additionally, whenever a tax location validation is run, the results are documented in the account's Activities. A successful validation will show the two pieces of evidence that matched. A failed validation will show all four evidence options so that you can see what was missing or needs to be changed.

Failed Validation Activity

Failed Validation Activity

Successful Validation Activity

Successful Validation Activity

How to Fix an Invalid Account

If the account is invalid, the you will need to work with the invalid customer to update their evidence options before subscription renewal, otherwise the subscription will expire at renewal. Use the activity event in the Activities section of the customer's account to show you which pieces of evidence were wrong, as well as your options of what can be updated. Remember, the taxable address is the master address, so you need to check whether that was the Billing Address or the Account Address and match against that. Finding a match between two pieces of evidence that do not include the invoice address will not result in a valid account. If the taxable address is the Billing Address, an easy way to add a matching piece of evidence is to confirm with the customer that they are physically located in the same country as their Billing Address and update the Account Address to have that country.

Subscription Sign-ups

If a subscription sign-up triggers location validation and the validation fails, the purchase will be blocked and the customer will see the below error message:

<errors>
    <error field="invoice.base" symbol="tax_invalid_location">You are located in the European Union but your country cannot be verified for VAT. Please try again or contact the merchant.</error>
</errors>
<errors>
    <error field="invoice.base" symbol="tax_invalid_location">You are located in New Zealand but your country cannot be verified for GST. Please try again or contact the merchant.</error>
</errors>

Recurly will not send an email to your Billing Contact email address when a sign-up fails due to Tax Location Validation. If you would like to track these failures and are using our API, you can listen for the specific error message and log the form details on your side.

Subscription Renewal

At renewal, if the account is marked as valid, the invoice will be created and the subscription will renew. If the account is marked as invalid, the subscription renewal will automatically fail and the subscription will expire. If the account is not marked as valid or invalid, Location Validation will run, mark the account, and either allow the invoice to be created or terminate the subscription.

When a subscription expires due to Tax Location Validation, the expiration reason will be Tax Location Invalid. This expiration reason can be seen in the Subscriptions - Churned export and the Churn Analysis report.

Subscription Changes

If a subscription change (downgrade/upgrade) triggers location validation and the validation fails, the change will be blocked and the customer, or you in the Admin Console, will see the same error as a sign-up, detailed above.

Invoice Evidence

When an invoice is successfully posted on an account with valid tax location evidence, the two pieces of evidence are stored and retrievable from the "Invoices - Summary" export in the invoice_country and evidence_matched columns.

View documentation on the full Invoices - Summary export here.

Invoices - Summary export

Invoices - Summary export

Name
Example
Description

invoice_country

FR

This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled. Column shows the EU or NZ country code of the customer's address on the invoice. The country refers to the evidence_matched.

evidence_matched

Account Info Country, Billing Info Country, IP Address Country, Credit Card BIN Country

This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled. Column shows the two pieces of evidence that matched when the invoice was created. The corresponding country is the invoice_country.

Manual Invoices Not Supported

If Tax Location Validation is enabled, only automatically collected invoices will be checked for a valid taxable address before posting. Manual Invoicing does not support Tax Location Validation because manual collection invoices use the Account Address as the taxable address and usually imply that the customer is not going to provide billing information. Without the billing information, the three other evidence options, Billing Address, IP Address and Credit Card BIN do not exist. It is up to the merchant to collect a second piece of location evidence for manual invoices and store those details. One option is to store the evidence details in one of the invoice notes sections before posting.

If your Tax Settings are configured to use Account Info Address for all invoices, you may still see a validation notice on an account that cannot be validated, but when the subscription is Manual Collection, it will not cause the subscription to cancel. You can safely disregard the notice for Manual Collection subscriptions.

Testing

Full Tax Location Validation can be tested in sandbox mode.

Updated 5 months ago

Tax Location Validation


Australia, the European Union and New Zealand all require two pieces of evidence proving the country of the customer before tax can be collected on a digital services sale to a consumer. Recurly's Tax Location Validation automates this compliance for your business.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.