Overview

Required plan

This feature or setting is available to all customers on any Recurly subscription plan.

Additional cost

This feature or setting requires an additional cost. Please reach out to your Recurly account manager or [email protected] for more pricing details.

Limitations

Our integration with Avalara for Communications (AFC) is designed to streamline your operations and is specifically optimized for the streaming media industry. However, there are some limitations that you should be aware of:

Non-Billable Taxes and Surcharges: Taxes and surcharges that Avalara categorizes as non-billable are not included in our invoices.
Disabling AFC: If you choose to disable AFC, refunds of invoices that include taxes will not be processed.
Switching to AFC: If you decide to switch providers to AFC, refunds that include charges from various tax services will not be processed.
Tax Exemptions: Tax exemptions at the account level are limited to "yes" or "no" options, excluding the possibility for complex jurisdiction level exemptions.
Customer Type: An account's customer type is not editable and defaults to "residential".
Lifeline Participant Status: An account cannot hold a status as a lifeline participant.
Telecommunications-specific Billing Units: Recurly does not support taxation based on billing units specific to telecommunications, such as "Minute", "Line", or "Location".

Definition

Avalara for Communications (AFC) is a service designed to meet the specific needs of communication service providers delivering VoIP, IoT, Streaming, and other voice or data transmission services via various platforms such as wireless, cellular, cable, or satellite. By integrating AFC with Recurly, providers can automatically apply communication taxes to their invoices and enable AvaTax to remit these taxes and fees to the relevant authorities. For more information about Avalara for Communications, visit here.

Key benefits

Flexible tax management: AFC enables accurate calculation and application of appropriate taxes to various transaction types like subscriptions, one-time charges, and add-ons.
Comprehensive coverage: Cover a wide range of tax jurisdictions for precise and up-to-date tax calculations, aiding compliance across diverse geographical areas, including international locations.
Tax exemption handling: Designate specific customer accounts as tax-exempt for efficient tax management and compliance, through the collaborative functionality of Recurly and AFC.
Downtime management: Protocols are in place to handle tax considerations during Avalara service downtimes, ensuring uninterrupted tax management.
Testing and validation: Test AFC integration using a sandbox site for accurate setup before going live, with Recurly validating Avalara credentials periodically to prevent disruptions.
Detailed reporting: Access detailed tax reports for easier reconciliation and transparency during tax filing periods, courtesy of the combined functionality of Recurly and AFC.

Key details

Understanding communications taxes and surcharges

Many local and state governments across the United States have established laws that impose surcharges and taxes on communications services. This includes Over-The-Top (OTT), Voice over IP (VoIP), and streaming applications, with the Chicago Amusement Tax being a notable example. The complexity of these regulations continues to increase over time.

Who should use Avalara for communications?

If your business offers a communications product and utilizes Recurly for subscription management, you might greatly benefit from our Avalara for Communications integration. However, the nature of your offerings may make sales and use tax software more suitable. To determine which option is best for your business, please reach out to our sales team.

How does the integration work?

The integration between Recurly and Avalara for Communications (AFC) is made possible through both Recurly's and Avalara's publicly available APIs. This allows for the application of sales tax, communications taxes, and communications surcharges as invoices are generated in Recurly. Each product setup or purchase initiated via Recurly necessitates a transaction and service type, which are linked to the tax surcharge rates enabled for your jurisdictions in AFC. The customer's address registered in Recurly assists AFC in determining the applicable amounts for each invoice.

Invoice appearance

The appearance of your invoices greatly depends on the jurisdiction involved. For most jurisdictions, a simple sales and use tax will be applied. However, for complex jurisdictions and services involving multiple taxes and surcharges, these will be displayed on the invoice in a detailed format. This way, both you and the merchant can understand what is being billed. Many jurisdictions allow you as a communications provider to pass the tax and surcharge amounts on to your customers.

Integration setup

Merchant tax address

Avalara requires the merchant's address for each invoice to calculate taxes. This is referred to as the "Origin" address. Recurly utilizes the Business Entity's company address(s) as the Origin address that gets transmitted to Avalara. For the Avalara integration to operate, the following criteria must be fulfilled in your Recurly Business Entity’s company address:

A country and postal code must be present.
The address must align with your Organization's "Company Address Settings" in Avalara.

Customer tax address

The customer's address is crucial for tax calculations. If the customer's location isn't known, tax calculations via Avalara aren't possible.

Determining the address to tax

You can calculate taxes based on either the Billing address or Account address. While many merchants collect and store a physical address in the Account Information, Recurly, by default, taxes the Billing address for automatic transactions and the Account address for manual invoices.

To change your tax address to the Account address, navigate to Configuration > Taxes > Tax Settings and enable "Use Account Information Address for all Invoices". Once this option is enabled, all invoices will use the Account Information address as the customer's address. If an Account address doesn't exist for a customer, the Billing address will be used as the default.

Required address fields

Although obtaining the complete customer address ensures the most accurate tax calculations, requiring additional information can potentially discourage purchases. We recommend consulting with Avalara to determine the minimum address requirements for your tax jurisdictions.

At the very least, Recurly requires a country to calculate taxes, even if Avalara can compute the tax without it. Upon enabling your AFC taxes, the country will automatically be required in the Billing address for all new signups. If the country isn't automatically required in the Account address, and you're taxing based on the Account address, ensure that the customer's country is stored.

If a renewal receives tax from Avalara but lacks a customer country in Recurly, Recurly will generate a silent error, and the renewal will be halted until a country is added. As it's challenging to identify which subscriptions are halted due to a missing country, we strongly advise conducting an address audit and updating all addresses with a country before activating taxes.

Avalara Address Validation

Any invoice that receives tax will require a customer's country. Without a customer country, the invoice will be blocked, or the subscription will be queued and won't renew until a country is added. Therefore, it's crucial to audit all customer addresses before beginning to tax and ensure that all addresses or those in taxable regions include a country.

By default, our integration with AFC will validate all customer addresses. If an address is invalid, an error will be returned, blocking the purchase. Here are the potential error messages that Recurly will return in the API, and on the Hosted Pages, including Checkout pages:

The address provided is invalid, and could not determine taxing jurisdictions.
The state/province provided is invalid, and could not apply tax.

Renewals won't be blocked if an invalid address error occurs, but the invoice produced will be rejected by Avalara and won't be considered for tax calculation. To limit disruptions with your current customers, renewals aren't blocked. As it's not straightforward to identify accounts with invalid addresses that didn't receive tax, we strongly advise auditing addresses and updating them before activating 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 allows purchases with invalid addresses to proceed in Recurly, but Avalara will reject the invoice, and it won't be considered for tax calculation.

Alter one-time charge flows

Similar to how plans and add-ons are managed, all one-time purchases require a T/S pair. If this pair is not set on one-time charges, it defaults to 0/0 - meaning no tax will be applied to the line item.

Changing tax jurisdictions

Overrides or exemptions for tax jurisdictions must be set by your Avalara account representative within a new AFC Client Profile; it cannot be done through Recurly. This Client Profile is what contains the jurisdictional rules for specific T/S pairs. It's advisable to use different Client Profiles because AFC doesn't track when tax jurisdictions are enabled/disabled, which could potentially result in improperly taxed refunds.

For best practice, schedule these events for the first day of the month to ensure that taxes cover a complete period.

However, keep in mind the current limitations in Recurly when using multiple Client Profiles:

T/S Pairs must be consistent across Client Profiles. If a T/S Pair exists in Client Profile 1 but not in Client Profile 2, all new charges will be invalid until the configuration of the object is updated.
Refunds that contain charges from multiple charge invoices (like subscription downgrades, for example) cannot span multiple Client Profiles.

Tax previews

Recurly supports tax previews for AFC customers via the API in the Preview Subscription, Preview Subscription Change, Preview Purchase, and Preview Invoice endpoints. These calls enable Recurly to query AFC directly for tax information and return it in the preview. However, Recurly.js, the Recurly Admin Console, Checkout and the Hosted Payment Pages do not yet support tax previews for AFC.

Tax exempt customers

Recurly gives you the ability to mark specific customer accounts as tax exempt, which excludes the account from future taxes. To mark an account as tax exempt, you'll need to edit the Account Information to reflect the customer's exempt status. Keep in mind that once a customer's status is set as exempt or non-exempt, it can't be changed. This is to ensure that there are no improperly taxed refunds or credits.

Test your integration

Testing your integration can be done on a sandbox site. Configure your sandbox site using all of the instructions mentioned above. When entering your AFC credentials, use the sandbox environment option.

There are a few things to remember when testing:

You won't be able to commit paid invoices to Avalara in sandbox mode.
If you're testing on the same site you plan to use for production, make sure you switch the environment to production on your AFC credentials page once you transition your Recurly site to production mode.

Recurly populates extra information on AFC line items from the corresponding Recurly line items, which can be beneficial for reconciliation and reporting from your AFC account:

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

The primary use case for our integration with AFC involves communications fees and surcharges, which are prevalent in the United States. However, there are some fees in other countries, and merchants may want to use one Recurly instance to sell into different nations. Merchants with their own AvaTax account can stay compliant with international VAT taxation using Recurly's integration with AFC.

As a best practice, create different plans and items for purchases in different countries, as these generally require different T/S pairs in Avalara. Presently, our object mapping is 1-1 with T/S Pairs, but this may change in the future.

Consult with your Avalara representative to figure out the appropriate T/S pairs for your products to ensure proper taxation in different countries.

Invalid Avalara credentials

Recurly validates your Avalara credentials whenever they are added or edited to prevent 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 has expired, or if Avalara experiences authentication service issues.
When your credentials are determined to be invalid, Recurly will notify your Technical Contact via email. If no Technical Contact is specified, the email will go to your Billing Contact. If you haven't specified a Billing Contact, the email will be sent 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 (i.e., you are testing Avalara), Recurly will disregard your credentials and cease sending requests to Avalara when an invoice is created. This means that each invoice will not include tax until your credentials are fixed.

Handling Avalara downtime

Recurly sends a request to Avalara for tax calculation whenever an invoice is created on a site with AFC credentials. If Recurly cannot get a response from Avalara or if the internal Recurly tax service that communicates with Avalara is unresponsive, Recurly's response will depend 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" status.

New sign-ups and purchases

For new sign-ups and purchases, if Recurly cannot get a response from Avalara or if the internal Recurly tax service is unresponsive, the signup or purchase will be blocked (meaning neither a subscription nor an invoice will be created). This is to ensure that no invoice for a customer in a taxable location is created without a tax consideration.
If you 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. Go to Configuration > Taxes > Tax Settings > Tax Service Settings and disable "Require tax response from tax service".

Future subscriptions and renewals

For future subscriptions and renewals, if Recurly can't get a response from Avalara or if the internal Recurly tax service is unresponsive, Recurly won't activate a future subscription or renew a subscription, but will keep retrying the activation or renewal every hour until a response is received from Avalara. This functionality cannot be configured or changed.
However, if Avalara's tax service returns an error during a renewal, the renewal will be processed without tax.

Disable tax response requirement

If you want to allow new purchases even when tax can't be calculated, go to Configuration > Taxes > Tax Settings > Tax Service Settings and disable "Require tax response from tax service".

With this setting off, invoices will be created without tax if Avalara or Recurly's tax service is down. You'll need to use Invoices - Summary export or Invoices API to track these invoices.

Remember, it's not possible to charge missing tax later. The only way to recover it is to refund and reissue the invoice. We recommend you disable this setting only if you're willing to cover the missing tax yourself.

Integration setup

Setting up your Avalara for Communications (AFC) integration with Recurly involves several steps. Following these accurately ensures your taxes are calculated and applied correctly.

Note: Be sure to double-check all the details during setup to avoid any discrepancies in tax calculation later on.

Confirm your business entity company address: Make sure the address is accurate as it can affect the tax calculation. If you are on a Recurly Elite plan, you may have multiple Business Entities and thus can set up multiple tax addresses.
Decide the customer address to tax: Choose between the billing address or account address.
Update your purchase form: The form should require at least the minimum address fields needed for your tax regions.
Update purchase or subscription change previews: Use Recurly's APIs for the tax preview portion (please note this isn't possible via Recurly.js).
Enter your AFC credentials on your sandbox site: This is the first step towards testing your integration.
Configure Your Plans and Add-ons: Assign the correct Transaction and Service Types for each product you sell to test your integration effectively.
Confirm the current customer addresses: Make sure they are correct and include a country.
Mark any tax exempt current customers: Do this in their Account Info.
Go live: Enter your AFC credentials on your production site and configure your plans and add-ons Transaction and Service Types.

Connect your AFC account

Connecting your AFC account to Recurly enables you to configure the Transaction and Service Types for your offerings. Here's how to do it:

Confirm your site is in Production Mode: You can test in Recurly sandbox mode, but this is limited to Avalara's sandbox environment.
Navigate to the Taxes Section: This is located in the left-hand navigation menu.
Click 'Connect' under AFC's Logo: This is found on the right sidebar of the page.
Enter AFC Credentials: These include your AFC Username, Password, Client ID, and Client Profile.
Adjust AFC Business Settings: These settings should match how you are registered to tax.
Determine Tax Records Commitment: Decide whether you want Recurly to commit your tax records in Avalara when an invoice is marked as paid in Recurly.
Select Avalara Environment: Choose either Sandbox or Production, depending on your current needs.
Select Account Identifier to send to Avalara: By default, Recurly Account Codes are used, but you can choose Recurly Account IDs.
Save Changes: Click this once you've confirmed all information is correct.

Configure plans and add-ons

To calculate taxes, Recurly needs to send Avalara line items for which you configure the Transaction Type and Service type (T/S pairs).

Navigate to Configuration → Plans: Select a plan and click Edit.}
Enable Tax for the Plan: This exposes a Transaction Type field and a Service Type where you can place your Avalara T/S pairs for the plan-level fee.
Setup Fee T/S Pairs: If you have a setup fee, it will use the same T/S pair as the plan fee.
Configure Add-on T/S Pairs: Each add-on can have its own T/S pairs.
Save your plan: Any customer in one of your tax jurisdictions that purchases this plan will now be taxed.
Learn more about transaction type and service type pairs from AFC here.

FAQs

Q: How are gift card initial purchases treated for tax?

A: For initial gift card purchases, we transmit a 0/0 (non-taxable T/S pair) to Avalara, signifying that tax does not typically apply to the purchase transactions, but applies when the gift card is redeemed.