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    

Vertex

Merchants on the Recurly Enterprise plan can enable global tax calculation on their Recurly invoices by connecting a Vertex O Series or Vertex Cloud account. Recurly supports both the on-premise and on-demand versions of Vertex O Series and Vertex Cloud, versions 7.0 and 8.0.

Get to Know Vertex

Don't have a Vertex account and want to learn more? Contact Recurly Sales or Support and we'll connect you with the right Vertex contact.

Integration Overview

  • Connect your Vertex O Series on-premise or on-demand, or Vertex Cloud, account by simply entering your credentials into Recurly.
  • Versions supported are 7.0 and 8.0.
  • Once a Vertex account is connected, all invoices created in Recurly send an InvoiceRequest to your Vertex instance, entering the invoice in the Vertex Tax Journal.
  • In the event an invoice needs to be removed from the Vertex Tax Journal, like when a purchase fails due to a declined credit card, Recurly sends another InvoiceRequest to Vertex for the opposite amount to offset the first invoice.
  • Your Recurly product codes (e.g. - plan code, add-on code or adjustment product code) are sent to Vertex as the Product of the line item.
  • Assign Tax Codes in Recurly to groups of products with the same taxability, which are sent to Vertex as the Product Class of the line item.
  • Invoice and line item tax rate, amount, type and region are stored in Recurly and accessible via exports and API for your tax reporting.

Go Live with Vertex Checklist

  1. Confirm your Site Settings 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.

Enable Vertex

To use the Vertex integration, you must be on the Enterprise Recurly plan and have the recently released Credit Invoices feature enabled on your site. If you are on Enterprise, contact Recurly Support to have the Vertex option added to your site.

Once Recurly Support has given your site access to Vertex, to enable Vertex, go in the Recurly Admin Console to Configuration > Taxes. Click on “Connect to Vertex” in the right sidebar. Enter the following credentials:

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/CalculateTax80?wsdl, then enter https://vertex-prod.yourcompany.com. Recurly will append the /vertex-ws/services/CalculateTax80?wsdl to the end of your url and switch out 80 for 70 depending on the version you select.

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 or 8.0. Select which version you are on.

Once your Vertex credentials are added, you will see them on the Taxes page and can test the connection any time by clicking “Test Configuration”. If you need to change your credentials, click “Configure”.

Test Vertex

To test your Vertex integration, we recommend adding credentials for a test Vertex instance on your Recurly sandbox site. 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, 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.

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.

Vertex Product

To associate each product in Recurly with a product rule in Vertex, configure each Recurly product code (plan code, add-on code, adjustment product code) to be a “Product” rule in Vertex. 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.

Vertex Product Class

The recommended configuration 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. Note that if the 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.
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.

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.

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.

Your Merchant Address and Tax Registration Numbers

Your merchant address that shows on the invoice is configured in the Recurly Admin Console under Configuration > Site Settings. 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 Site Settings. When there is a value in these fields, they will show on all customer invoices under your address.

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

Invoice previews with Vertex are supported in the API with these calls:

  • Preview Subscription
  • Preview Subscription Change
  • Preview Purchase
  • Preview Invoice

Recurly.js Pricing does not support Vertex tax previews.

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

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
  • Voided credit invoice - will send a positive Invoice Request

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.

Field Mapping

This section breaks down what Recurly data is sent to Vertex.

Recurly Attribute
Vertex Attribute

Invoice number

Request/documentNumber

Invoice posted date

Request/documentDate

Invoice currency

Request/isoCurrencyCodeAlpha

Vertex credentials/company

Request/Seller/Company

Vertex credentials/division

Request/Seller/Division

Site settings address

Request/Seller/PhysicalOrigin
Request/Seller/AdministrativeOrigin

Customer account code

Request/Customer/CustomerCode

Invoice taxable address (e.g. - Bill To or Ship To)

Request/Customer/Destination
Request/LineItem/Customer/Destination (for credit line items)

Invoice taxable address VAT number

Request/LineItem/Customer/TaxRegistration

Line item product code (e.g. - plan code, add-on code)

Request/LineItem/Product

Line item tax code

Request/LineItem/productClass

Line item subtotal after discounts

Request/LineItem/ExtendedPrice

Line item's original invoice number (for credit line items)

Request/LineItem/FlexibleFields

Line items' original invoice posted date (for credit line items)

Request/LineItem/taxDate