Vertex

🚧

Vertex Integration Validation

Recurly supports a core set of Vertex tax parameters that should work for most common taxation scenarios, but validation via a sandbox integration should be done to ensure this configuration meets your tax needs.

Go Live with Vertex Checklist

1. Confirm your Business Entity company address is filled out and correct.
2. Decide which customer address you want to tax: billing, account, or shipping.
3. Update your purchase form to require at least the minimum address fields needed for your tax regions.
4. Confirm the current customer addresses you are going to tax are correct and include a country.
5. Configure your plans and charges with the correct taxability and tax codes.
6. Enter your Vertex credentials on your production site before you enable the tax jurisdictions in Vertex.
7. Update any purchase or subscription change previews to use Recurly's APIs for the tax preview portion, not Recurly.js.
8. Mark any tax exempt current customers in their Account Info.
9. Test your integration on a sandbox site.
10. Go live by turning on your tax jurisdictions in Vertex.

Your Merchant Address and Tax Registration Numbers

Your merchant address that shows on the invoice is configured in the Recurly Admin Console under Configuration > Business Entities. This address is what Recurly sends to Vertex as the merchant address. The address must be a real address or Vertex will throw an error. Additionally, you must have at least a country and postal code.

Recurly provides two fields for tax registration numbers, the “VAT Number” field and the “Registration Number” field. These are also found in your Business Entity. When there is a value in these fields, they will show on all customer invoices under your address.

Customer Address Collection

When taxes are enabled, Recurly requires you to collect country from customers at a minimum. If you do not want to ask your customers for their country, you can infer it from other evidence you have and set the country for them in the request to create the address in Recurly. Ensure that you are collecting enough address elements for Vertex to tax properly for the taxable region. Learn about what is considered the taxable address on the invoice here.

Note that if there is no address, Recurly will not identify the invoice as needing taxes and will not send the invoice to Vertex.

If you have existing customers that will be taxed, you will need to ensure their address has a country currently and any additional address elements needed to tax properly. Learn more about existing customer addresses here.

Configure Plans and Charges

To map your Recurly products to taxability rules in Vertex, you can either use a one-to-one mapping with a Vertex Product or assign a group of products in Recurly to use the same Vertex Product Class.

Using Vertex Product

To associate each product in Recurly with a product rule in Vertex, configure each Recurly product code ("Plan Code", "Add-On Code", "Item Code", and adjustment "Product Code") to match a “Product” rule in Vertex. These Recurly product codes are sent to Vertex as the Product of the line item. This configuration option requires no changes in Recurly, but does require you to consistently keep Vertex up-to-date with your Recurly product codes changes. This is likely not ideal for large product catalogs.

Using Vertex Product Class

The recommended configuration for mapping your Recurly products to Vertex taxability rules is to use Vertex’s Product Class. Create a "Product Class" in Vertex for each unique taxability rule and then set that Product Class as the “Tax Code” of the appropriate products in Recurly. These Recurly tax codes are sent to Vertex as the Product Class of the line item. This approach requires the tax codes in Recurly to remain up to date if product classes are changed in Vertex.

🚧

Note that if a line item has both a Product and Product Class mapped via the product code and tax code in Recurly, Vertex will use the Product rule over the Product Class rule. If a line item has neither a product code nor tax code that match Products or Product Classes in Vertex, then Vertex's default physical goods tax rules will be applied.

Recurly Tax Codes

If you are not currently using Recurly Taxes powered by Avalara, and you have the Vertex feature on your site, you will see the ability in the API and Recurly Admin Console to set a Tax Code for your plan fees, add-on fees, and one-time charges. Depending on your circumstances, we have different recommendations for when to set Tax Codes in your go-live steps.

No Existing Subscribers

If you do not have invoices flowing through Recurly in production mode, make sure you set your tax codes and add your Vertex credentials before you start sending customers through Recurly.

Existing Subscribers, No Taxes Enabled

If you have existing subscribers being invoiced through Recurly and those invoices are not taxed, start by ensuring Vertex can receive the invoices and not return tax. Connect your Vertex credentials, but do not have your tax jurisdictions enabled in Vertex. Then when you are ready to start taxing, enable the jurisdictions in Vertex, or schedule a future start date, and invoices will start returning tax.

If your customers in Recurly should not be taxed, but your Vertex account is being shared with another system that needs to tax the same region, define a product class in Vertex with a rule to return 0 tax for those regions. Then put that product class on your Recurly plans and one-time charges as the tax code. That will ensure no tax is returned.

Existing Subscribers, Taxes Enabled

If you are using Recurly Taxes powered by Avalara and transitioning to Vertex, you will not see the tax code field. Vertex will default to taxing your customers a physical rate, which matches the Recurly Taxes powered by Avalara. In Vertex, enable where you currently tax with a jurisdiction start date matching when you started taxing in Recurly. This is important to support refunds of invoices processed through Recurly Taxes powered by Avalara. Then add your Vertex credentials and invoices will start going to your Vertex account immediately. After this initial transition, you will see the tax code field and can start configuring your advanced taxability rules or add new jurisdictions. Note that if you are using Recurly's tax type field to denote physical vs. digital for EU taxes, you will need to configure Vertex with a product class of "D0000000" and map it to a digital services taxability rule before you add your Vertex credentials.

If you are using your own Avalara account and transitioning to Vertex, you will need to configure all of your current tax codes as product classes in your Vertex account, mapping to the correct taxability rule based on Vertex's guidance. Only after your current product class codes are configured in Vertex should you add your Vertex credentials in Recurly. You will need to keep these Avalara codes defined in Vertex to ensure refund support.

Connect Your Vertex Account

To use the Vertex integration, you must be on the Elite or Enterprise Recurly plan and have the Credit Invoices feature enabled on your site (Configuration > Invoice Settings in the Recurly Admin Console). If you do not currently have Credit Invoices enabled, please review the feature details before enabling to ensure this change is fully understood. We recommend connecting your Vertex account to Recurly before you enable your tax jurisdictions in Vertex in order to allow time to configure your Recurly account for taxes before you begin collecting taxes in those jurisdictions.

If you are on Elite or Enterprise plan, have Credit Invoices enabled, and have a Vertex O Series or Vertex Cloud account, follow the steps below to enable Vertex for your Recurly site:

1. Contact Recurly Support to have the Vertex option added to your site.
2. Once Recurly Support has given your site access to Vertex, select the Taxes section in the left-hand navigation.
3. Click “Connect to Vertex” in the right sidebar.
4. Have your Vertex Endpoint, Trusted ID, Company, Division, and Version ready and enter those values on the form. See descriptions below for additional information.
5. Click Save Changes.
6. Before proceeding, test the connection by clicking the Test Configuration button to ensure the connection is made properly.

Endpoint

Enter the url where your wsdl is hosted, up to the ".com" portion. You must provide a secure https url. For example, if your url is https://vertex-prod.yourcompany.com/vertex-ws/services/CalculateTax90?wsdl, then enter https://vertex-prod.yourcompany.com. Recurly will append the /vertex-ws/services/CalculateTax90?wsdl to the end of your url and switch out 90 for 80 or 70 depending on the version you select. See our IP Allowlist documentation for a list of IP addresses to allow through.

Trusted Id

Every Vertex instance has a trusted id. This is your API password. Recurly does not use a username and password to ensure your tax collection is not shut off due to a user lockout or accidental password reset or deletion. If you are not sure what your Trusted Id is, please contact Vertex.

Company

This is the taxpayer in your Vertex instance with the jurisdiction rules that will apply to your invoices. If you have a division as well, this is the parent taxpayer.

Division

This is the child taxpayer in your Vertex instance. If you have a division, it is likely this taxpayer that has the jurisdiction rules that apply to your invoices.

Version

The Recurly Vertex integration currently supports either O Series or Cloud 7.0, 8.0, or 9.0. Select which version you are on.

Invoicing

Once Vertex is enabled, all customer invoices are sent to your Vertex account, regardless of whether you are taxing in their location. When an invoice includes tax, the line item table will have an additional Tax column that shows the rate for each line item. Additionally, below the line item table there will be a tax section showing the total tax amount for the invoice. This section shows below Subtotal and above Total and will show the location, tax type and rate (e.g. “FR VAT 20%” for French VAT).

Tax Previews

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

Previews are sent to Vertex as a Quotation Request and will not create entries in the Tax Journal.

Tax Inclusive Pricing

Tax inclusive pricing is available using Vertex. Please see the Tax Inclusive Pricing page for more information.

Issued Invoices

All invoices issued in Recurly will send an Invoice Request to Vertex, which creates an entry in the Tax Journal. Charge invoices send a positive Invoice Request and credit invoices send a negative Invoice Request. A credit invoice event would be a refund, subscription change, or write-off. Note that one-off credit invoices will not go to Vertex because they are not related to a charge invoice and therefore will never have tax.

There are a few scenarios where Recurly will follow-up with an additional request for the invoice in order to remove it from the Vertex Tax Journal:

• Failed purchase due to credit card decline - will send a negative Invoice Request for the opposite amount to offset the first invoice
• Voided credit invoice - will send a positive Invoice Request

Exempt Products or Customers

In the event you want to force a line item to be tax exempt, you can do so at the plan, account, or one-time charge level. When configuring a plan or creating a one-time charge, you will see the ability to turn off tax collection. When editing an account’s account information, you will see the option to make the account tax exempt. In the API this is the tax_exempt attribute for all of these.

When an account is exempt, all invoice line items are treated as exempt. When a plan is exempt, all subscription line items for the plan are treated as exempt. When a one-time charge is exempt, just that line item is treated as exempt. In all cases, an exempt line item sends Vertex an override to force the line item as exempt.

Alternatively you can always configure a Product or Product Class in Vertex that ensures the line item is exempt.

Test Your Integration

To test your Vertex integration, we recommend adding credentials for a test Vertex instance to your Recurly sandbox site. Configure your sandbox site following all of the instructions above.

When you are ready to go live with the integration, put your production Vertex credentials on your production Recurly site. Note that once Vertex credentials are added on your production Recurly site, your integration is live and all invoices are flowing to Vertex. Due to this, please read all of the documentation and test your integration before going live.

Disable Vertex

In the event that you need to disable your Vertex integration, you can click “Disable Vertex” on the Taxes page. Disabling Vertex will clear all tax codes configured in your plans and will turn off tax collection on your invoices.

Reporting

Invoice and line item tax rate, amount, type, and region are stored in Recurly and accessible via exports and the API for your tax reporting.

Errors and Downtime

By default, Recurly will block purchases when an error is returned from Vertex. You can disable the block on address or downtime errors in the Recurly Admin Console under Configuration > Taxes > Tax Settings under “Tax Service Settings”.

Renewals are treated differently depending on the error. If the error is an address error, the renewal will go through without tax. This happens because there is no human around to correct the error and we do not want to hold up the renewal. If the error is a downtime error, the renewal will queue and retry until a response is received. We retry on downtime errors because they usually resolve in a short period of time.

FlexibleFields

On integration setup, we allow you to specify a FlexibleField ID and the value you would like to pass into that FlexibleField for all Recurly documents (charge and credit invoices). This value allows you to segment the data from a specific Recurly site from all other data you have in Vertex. For example, for FlexibleField ID "25" you could pass "Company ABC" and then you would be able to see in Vertex all transactions labeled with Company ABC in that field.

Field Mapping

This section details the fields that Recurly sends to Vertex with each invoice that is created. This core set of data fields supports basic tax configurations. If you require additional fields as part of your tax setup, contact your Vertex rep and Recurly Sales or Support to see if that request can be supported.

Limitations

Vertex requires that the Customer Code be 40 characters or less. Recurly allows up to 50 characters for Account Code, so you will need to ensure that your Recurly Account Codes are within Vertex's character threshold to prevent transaction declines.