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    

Avalara for Communications (AFC)

The Avalara for Communications integration is built for communication service providers offering VoIP, IoT or Streaming services, transferring voice or data through wireless, cellular, cable, satellite or any other consumer or business methodologies

Integrate your Avalara AvaTax for Communications account with Recurly and have communication taxes applied on your invoices automatically, and so that AvaTax can remit payment to the appropriate authorities of these taxes and fees.

Learn more about Avalara for Communications.

Introduction

What are communications taxes and surcharges?

Many United States state and local governments have passed laws requiring the application of surcharges and taxes on communications services, including OTT, VOIP, and streaming applications. A good example of these is the Chicago Amusement Tax. These regulations continue to be more complex over time.

The laws in many of these jurisdictions allow you as a communications provider to pass the tax and surcharge amounts on to your customers.

Optimized for Streaming Media, not Telecommunications

Avalara for Communications supports a variety of use cases across the telecommunications and streaming media industries. Recurly's implementation is optimized for streaming media, so the current limitations of the integration include:

  1. Account-level tax exemptions are "yes" or "no", so you cannot select complex jurisdiction level exemptions.
  2. An account's customer type is not editable and is set to "residential".
  3. An account cannot be a lifeline participant.
  4. Recurly does not support taxation by telco-related billing units. There is no option to select transaction and service types that are specifically for "Minute", "Line" or "Location".

If you have any questions, please reach out to our support team.

Who should use Avalara for Communications?

Businesses who have a Communications product and who use Recurly for subscription management are good candidates for our Avalara for Communications integration. However, depending on what you are selling, it could be that you are better suited to use sales and use tax software. For more information on whether or not your business could benefit, please contact our sales team.

How does the integration Work?

Recurly integrates with AFC through Recurly's and Avalara's publicly available APIs, and adds sales tax, communications taxes, and communications surcharges as invoices are created in Recurly. Each product you set up or purchase that you initiate through Recurly requires a transaction and service type, which correspond to tax surcharge rates enabled for your jurisdictions in AFC. The customer's address in Recurly helps AFC to determine the amounts to apply to each invoice.

How will my invoices appear to customers?

It heavily depends on the jurisdiction. Most jurisdictions will apply simple sales and use tax. But for complex jurisdictions and services which apply multiple taxes and surcharges, we will display these on the invoice in a detailed format so that both you and the merchant can understand what is being billed. An example invoice is below:

Integration Setup

  1. Confirm your Site Settings company address is filled out and correct.
  2. Decide which customer address you want to tax, billing address or account address.
  3. Update your purchase form to require at least the minimum address fields needed for your tax regions.
  4. Update any purchase or subscription change previews to use Recurly's APIs for the tax preview portion (this is not possible via Recurly.js).
  5. Enter your AFC credentials on your sandbox site.
  6. Configure your plans and add-ons with the correct Transaction and Service Types for each product you sell to test your integration.
  7. Confirm the current customer addresses you are going to tax are correct and include a country.
  8. Mark any tax exempt current customers as such in their Account Info.
  9. Go live by entering your AFC credentials on your production site and configuring your plans and add-ons Transaction and Service Types.

Merchant Tax Address

In order to calculate taxes, Avalara needs to know the merchant address for each invoice. This is called the "Origin" address in Avalara. Recurly uses the Site Settings company address on each invoice, so that is the Origin address we send to Avalara. In order for the Avalara integration to work, you must meet these criteria in your Recurly Site Settings company address:

  1. Have at least a country and postal code
  2. The address must match your Organization's "Company Address Settings" in Avalara

Customer Tax Address

The customer address is very important in taxes. If we don't know where the customer is located, we can't calculate taxes with Avalara.

Which Address To Tax

You have the option of calculating taxes based on Billing address or Account address. Many merchants collect a physical address and store this in the Account Information address. By default, Recurly will tax the Billing address for automatic transactions and the Account address for manual invoices.

To switch your tax address to the Account address, go to Configuration > Taxes > Tax Settings and enable "Use Account Information Address for all Invoices". Once selected, all invoices will use the Account Information address as the customer address. If an Account address does not exist for a customer, we will default back to the Billing address.

Which Address Fields to Require

It is always best to collect the full customer address to ensure the most accurate tax calculations, but we know that asking more information from customers can be a barrier to purchases. We suggest talking with Avalara about the minimum address requirements needed for your tax jurisdictions.

Recurly will require a country at a minimum in order to calculate taxes, even if Avalara is able to calculate the tax without the country. Once you enable your AFC taxes, the country will automatically be required in the Billing address for all new signups. The Account address will not require country automatically, but is needed if you are going to tax based on Account address, so make sure you are storing the customer's country.

If a renewal receives tax from Avalara but does not have a customer country in Recurly, Recurly will throw a silent error and the renewal will be stuck until a country is added. There isn't an easy way to know which subscriptions are blocked due to lack of country, so we strongly suggest you do an address audit and update all addresses with a country before turning on taxes.

Avalara Address Validation

All invoices that receive tax will need a customer country. If the invoice does not have a customer country, the invoice will be blocked or the subscription will be queued and won't renew until a country is added. Please do an audit of all customer addresses before you start taxing and make sure all addresses or those you can tell are in taxable regions have a country included.

By default, our integration with AFC will validate all customer addresses. If a customer address is invalid, an error will be returned and the purchase will be blocked. Here are the possible error messages Recurly will return in the API and on the Hosted Pages:

The address provided is invalid, could not determine taxing jurisdictions

The state/province provided is invalid, could not apply tax

Renewals will not be blocked if an invalid address error occurs, but the resulting invoice will be rejected by Avalara and will not be considered for tax calculation. We do not block renewals in order to limit disruption with your current customers. There isn't an easy way to know which accounts had invalid addresses and did not receive tax, so we strongly suggest you do an address audit and update addresses before turning on taxes.

You can disable Avalara address validation in your Tax Settings under Configuration > Taxes > Tax Settings. Deselect the checkbox next to "Use Avalara's address validation" and save your settings. Disabling address validation will allow purchases with invalid addresses to go through in Recurly, but the invoice will be rejected by Avalara and will not be considered for tax calculation.

Connect Your AFC Account

Once you have an AFC account, you can connect it to Recurly. By connecting your AFC account, you will be able to configure the Transaction and Service Types for the things you sell. Recurly will immediately attempt to collect tax on new invoices, however the Transaction and Service Types will default to 0/0 ("No Tax") to allow you time to configure them.

To enable AFC for your Recurly site, follow the steps below:

  1. Make sure that your site is in production mode. You can test in Recurly sandbox mode but are limited to Avalara's sandbox environment.
  2. Select the Taxes section in the left-hand navigation.
  3. Click "Connect" under "Avalara for Communication"'s logo in the right sidebar of the page.
  4. Have your AFC Username, Password, Client ID and Client Profile ready and enter those values on the form. The Client Profile is important when changing tax jurisdictions.
  5. Change the AFC business settings to match how you are registered to tax.
  6. Determine whether you want Recurly to set your tax records to committed in Avalara when an invoice is marked as paid in Recurly. The default is set to uncommitted.
  7. Select the Avalara environment - Sandbox or Production - you want to use. When you're processing real transactions, you should be sending transactions to Production.
  8. Select which Account Identifier to send to Avalara. Recurly Account Codes are typically set by you and are used by default. Recurly Account IDs are system generated IDs Recurly sets. If you are storing any potential PII in Recurly's Account Code (e.g. email address), you should select Account ID.
  9. Click Save Changes.

Configure Plans and Add-ons

Recurly will only send Avalara line items for which you configure the Transaction Type and Service type. We will refer to these as T/S pairs throughout this document.

Configure the plans and add-ons you want to tax under Configuration > Plans > Select a plan > Click Edit.

  1. Enabling tax for the plan will expose a Transaction Type field and a Service Type where you can place your Avalara T/S pairs for the plan level fee.
  2. If you have a setup fee, it will use the same T/S Pair as the plan fee.
  3. Each add-on can have it's own T/S pairs as well.
  4. Save your plan. Any customer in one of your tax jurisdictions that purchases this plan will now be taxed.

You can learn more about transaction type and service type pairs from AFC here.

Alter One-time Charge flows

Similar to plans, and add-ons, all one-time purchases will require a T/S pair. If this is not set on one-time charges, we will default to 0/0 - which will not apply tax to the line item.

Changing Tax Jurisdictions

To set overrides or exemptions for tax jurisdictions, reach out to your Avalara account representative to do so in a new AFC Client Profile; you cannot do so through Recurly. The Client Profile is what contains these jurisdictional rules for specific T/S pairs. We recommend using different Client Profiles because AFC does not track when tax jurisdictions are enabled/disabled which could cause refunds not to be taxed as their original invoice was.

It is best practice to schedule these events for the first day of the month to ensure taxes span a complete period.

Current limitations in Recurly when leveraging multiple Client Profiles include:

  • T/S Pairs must be consistent across Client Profiles. If a T/S Pair exists in Client Profile 1 but not Client Profile 2, all new charges will be invalid for as long as it takes you to update that object's configuration.
  • Refunds that contain charges from multiple charge invoices (subscription downgrades, for example) cannot span multiple Client Profiles.

Tax Previews

Recurly supports tax previews for AFC customers in the API in the Preview Subscription, Preview Subscription Change, Preview Purchase, and Preview Invoice endpoints. Using those calls, Recurly will query AFC directly for the tax information and return it in the preview. Tax previews for AFC are not yet supported by Recurly.js, the Recurly Admin Console, or the Hosted Payment Pages.

Tax Exempt Customers

Recurly allows you to mark specific customer accounts as tax exempt, removing the account from any future taxes. To mark an account as tax exempt, edit the Account Information to mark the customer as exempt. Note that once a customer is marked as exempt or non-exempt, this setting cannot be changed. This is intentional to ensure that there are not refunds or credits which are attempted to be taxed incorrectly.

Test Your Integration

You can test your integration on a sandbox site. Configure your sandbox site following all of the instructions above. When you enter your AFC credentials, you will use the sandbox environment option.

  • You will not be able to commit paid invoices to Avalara in sandbox mode.
  • If you test on the same site that you are going to move to production, make sure you switch the environment to production on your AFC credentials page after you move your Recurly site to production mode.

Recurly fills out extra information on AFC line items from the corresponding Recurly line items. This can be helpful for reconciliation and reporting coming from your AFC account come tax time:

  • Optional Field 1: Product Code
  • Optional Field 2: Item SKU (only present on Item line items)
  • Optional Field 3: Original Invoice Number (only for refund line items)

International Taxation

Communications fees and surcharges are very common in the United States and that is the main use case for our integration with AFC. However, there are some fees abroad, and merchants may want to use one Recurly instance to sell into different countries. Merchants using their own AvaTax account with Recurly can stay compliant with international VAT taxation using Recurly's integration with AFC.

It is best practice to create different plans and items for purchases in different countries, because they generally require different T/S pairs in Avalara. Currently, our object mapping is 1-1 with T/S Pairs, however that might change in the future.

Connect with your Avalara representative to determine out what the appropriate T/S pairs are for your products in order to tax appropriately in different countries.

Invalid Avalara Credentials

Recurly validates your Avalara credentials whenever they are added or edited to keep you from saving invalid credentials. Your Avalara credentials will become invalid in Recurly if your AFC account becomes "Inactive", meaning your sandbox or production Avalara account expired, or if Avalara is having authentication service issues.

When your credentials are determined to be invalid, Recurly will send an email to your Technical Contact. If you have not specified a Technical Contact, the email will go to your Billing Contact. If you have not specified a Billing Contact, the email will go to the first user on the account with Admin user rights. This email will only be sent once at the time the credentials become invalid.

If your Avalara site is in sandbox mode, meaning you are testing Avalara, Recurly will ignore your credentials and stop sending requests to Avalara when an invoice is created. This means each invoice will not have tax until you fix your credentials.

Handling Avalara Downtime

When an invoice is created on a site with AFC credentials, Recurly will send a request to Avalara for the tax to include on the invoice. In the event that Recurly cannot get a response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, Recurly will respond differently depending on whether the invoice is for a new sign-up or purchase, or a future subscription activation or renewal.

To check Avalara's status, visit http://status.avalara.com/ and expand the Avalara for Communications section to view the "Avalara AvaTax for Communications SaaS Pro REST".

For new sign-ups and purchases

If Recurly cannot get a response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, the signup or purchase will be blocked (neither a subscription or invoice will be created). This is to ensure that no invoice for a customer in a taxable location is created without a tax consideration. The following error will be returned:

  • "Tax service currently unavailable, please try again later"

Since all invoices are sent to Avalara, this sign-up or purchase block also affects invoices for customers in locations where you do not collect tax, tax exempt customers, or tax exempt line items.

Disable Tax Response Requirement

If you would prefer to allow new sign-ups and purchases to go through when tax cannot be calculated, you can change the default behavior for your site by going to Configuration > Taxes > Tax Settings > Tax Service Settings and disabling "Require tax response from tax service".

If you disable the tax response requirement, initial purchase invoices will be created without tax when Avalara or Recurly's internal tax service is unresponsive. Recurly will not notify you when an invoice is created without a tax consideration. To track these invoices, you will need to use the Invoices - Summary export or Invoices API to identify invoices in locations where you tax and no tax was charged on the invoice.

It is important to note that it is not possible to charge a customer only the missing tax after an invoice is created. The only way to collect the missing tax would be to refund the invoice and issue a new custom charge invoice. The custom charge invoice, while linked to the account, will not be linked to the subscription or underlying plan. Due to this, we recommend that merchants disabling the tax response requirement only do so if they plan to take on the missing tax fees themselves, and not collect the missing tax from the customer.

For future subscriptions and renewals

If Recurly cannot get a response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, Recurly will not activate a future subscription or renew a subscription and will keep retrying the activation or renewal every hour until a response is received from Avalara. While the renewal may happen an hour late, the underlying subscription dates will respect the original subscription billing cycle. We retry the activation and renewal to ensure that no invoice for a customer in a taxable location is created without a tax consideration. This functionality, unlike sign-ups and purchases, cannot be configured or changed.

If the Avalara tax service returns an error during a renewal, though, the renewal will be processed without tax.

Tax Amount Rounding

Many surcharges and taxes result in fractions of a penny being due (e.g. tax amount as 10.555% of $10 results in $1.555 in tax. Tax amount estimates in sandbox mode and previews in production mode are always rounded up to two decimal points.

We round up because rounding rules vary for different regions and jurisdictions. Actual invoices in production mode use Avalara for rate calculations. Avalara provides the appropriate rounding up or down for the region and jurisdiction. Avalara rounds on the line item level, not the invoice level. In most regions, normal rounding rules apply where any digit under 5 is rounded down and 5 and higher is rounded up.

FAQ / Limitations

  • How are gift card initial purchases treated for tax? For gift card purchases we send 0/0 (non-taxable T/S pair) to Avalara to reflect that tax does not normally apply on purchase transactions, but when the gift card is redeemed.
  • We do not include taxes and surcharges which are marked by Avalara as non-billable on our invoices
  • If you chose to disable AFC, refunds of taxed invoices will not be processed.
  • If you chose to switch providers to AFC, refunds that include charges from multiple tax services will not be processed.

Updated 5 months ago

Avalara for Communications (AFC)


The Avalara for Communications integration is built for communication service providers offering VoIP, IoT or Streaming services, transferring voice or data through wireless, cellular, cable, satellite or any other consumer or business methodologies

Integrate your Avalara AvaTax for Communications account with Recurly and have communication taxes applied on your invoices automatically, and so that AvaTax can remit payment to the appropriate authorities of these taxes and fees.

Learn more about Avalara for Communications.

Suggested Edits are limited on API Reference Pages

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