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    


Taxes relate to charges (subscriptions and one-time charges) and are applied to the invoice for payments. When setting up a site, you can configure collection of taxes as either US Sales Tax or VAT The tax will be calculated for the applicable combination of charges, plans and accounts. Invoices, exports, emails and webhooks will indicate the tax amounts included from your transactions.

US Sales Tax

Sales tax for subscription plans is supported by Recurly for US merchants. Recurly applies state, county, local and special tax rates when your subscriber is in a state that you've identified to collect tax in your tax settings.

Available Features

The current release of the US Sales Tax feature allows merchants to collect taxes in US tax regions on their new and existing subscription plans. The summary of features includes:

  • No Recurly plan change or upgrade is required. There is no additional cost for this feature.
  • The ability to set the tax regions where you need to collect US Sales Tax based on customer address (billing address for automatic invoices/account address for manual invoices).
  • Tax rates and amounts provided via our tax service partner, Avalara.
  • Set specific Plans as exempt.
  • Set specific Accounts as exempt, such as nonprofit or charity customers.
  • Toggle applying taxes for one-time charges.
  • Updates to invoices to display US Sales Tax along with improved layout of line item and totals calculations.
  • Select and process refunds by invoice line items. Refunds will apply the appropriate sales tax amount for each line item selected from an invoice.
  • Prorated sales tax amounts for Plan upgrades and downgrades where US sales tax was applied to the original plan and/or add-on
  • Updates to export reports for accounts, invoices and transactions to include US Sales Tax information.
  • Enabling tax calculations on the plan hosted payment pages.
  • Previewing estimated tax amounts for new subscription in the Admin Panel.
  • Enabling API objects with tax amounts and tax details.
  • Configuration of US Sales Tax via Recurly.JS V3 (BETA).
  • New invoice summary export that aligns to the invoice view.

Future features include:

  • Invoice line item export with the tax breakdown by state, county, state, special.
  • Full address tax support (based on your site address requirements).
  • A direct integration with Avalara to your own tax reporting account.
  • Ability to define product tax code.
  • Canadian tax support.
  • Enhancements to VAT tax support.

Configure US Sales Tax on your Account

US Sales Tax is available on all Recurly accounts where country is set to United States under [Site Settings][1]. To enable US Sales Tax for your site, follow the steps below.

  1. Select the Taxes section in the left-hand navigation.
  2. Click the Enable US Sales Tax button and agree to the terms.
  3. Select the regions to collect sales tax and click Save Changes.
  4. US Sales Tax will now be applied to new and existing invoices whose billing address is in the selected regions.

US Sales Tax Scenarios

  • US sales tax is determined based on matching data across configured tax regions and the customer’s billing address. This requires that you have a minimum of Postal Code set as the Address Requirement in your Site Settings.
  • US Sales Tax is only applied to charges in the currency US Dollars (USD).
  • The total tax amount and rate applied are reflected in invoices, exports (invoices & transactions), emails and webhooks (transaction).
  • In addition to subscriptions, US Sales Tax can also be applied to one-time charges from the Accounts page through the same Add Charge flow.
  • Specific plans can be set as exempt from taxes by going to plans and setting the plan as exempt. Otherwise taxes will be applied to plans according to the above scenarios.
  • Specific accounts can be set as exempt from taxes by going to Accounts and setting the account as exempt. Otherwise taxes will be applied to accounts according to the above scenarios.

Invoices and Exports

Invoices have been updated to support the display of US Sales Tax along with other enhancements to improve the readability of the format. US Sales Tax is calculated for the charges on an invoice, including proration adjustments for upgrade and downgrades. A customer must have a postal code and country in order for taxes to be calculated on an invoice. Automatic invoices (e.g. - credit card, PayPal), require this address information in the Billing address. You can view your invoice by going to the [Invoices][5] page. For general information about invoices, view the [invoices][4] reference page.

Exports will also provide US Sales Tax data. The transactions export will include the total tax amount applied to each transaction and the invoices export will include the line item tax and total tax amounts. For details on the available data fields, view the exports reference page.

VAT (Value-added Tax)

VAT, or value-added tax, is supported by Recurly for European merchants. Recurly handles VAT percentages across different countries and different purchasing scenarios.

Configure VAT on your Account

VAT is available on all Recurly accounts that have set an EU country in their configuration page. If you have not done so already, set your company country under Site Settings. To enable VAT for your site, follow the steps below.

  1. Select the Taxes section in the left-hand navigation under Configuration.
  2. Click the Enable VAT button.
  3. Input VAT Number and VAT Percentage and click Save Changes.
  4. Select the Hosted Payments Pages section in the left-hand navigation under Configuration
  5. Check the Show VAT number field checkbox under Optional Fields and click Update Payment Page
  6. VAT will now be applied to new and existing invoices according to the scenarios below

VAT Scenarios

  • If purchaser is outside of the EU, they will not be charged the VAT fee. This is determined by the country a purchaser provides in their billing information.
  • If purchaser is outside the company's country, but inside the EU, the purchaser will be charged the VAT fee. The purchaser can enter a VAT number in their billing information to avoid having the VAT charged.
  • If purchaser and company are inside the same country, the purchaser will be charged the VAT fee.


Recurly validates the VAT number for all production transactions against VIES. Please contact Recurly support if you'd like to disable VAT validation on your Recurly site.