Skip to main content
Sign in RESOURCES

Switching a Recurly Site to a New Avalara AvaTax Account

Tarek
  • Updated

If your Recurly site already uses Avalara AvaTax and you are moving to a new Avalara account, company, or production instance, plan the cutover before changing credentials in Recurly. The switch is usually handled by updating the Avalara credentials and company code in Recurly, then running a test configuration to confirm the new connection.

The most important work happens before cutover: make sure the new Avalara setup is ready to calculate tax correctly, receive Recurly invoice document codes, and preserve any historical tax records you need for compliance or reporting.

Key takeaway: Recurly doesn't need a data export to switch the Avalara integration itself. The Recurly side of the switch is usually limited to updating the Avalara credentials, company code, and environment, then validating the connection with Test Configuration. Historical Avalara tax documents, committed returns, exemption records, reporting history, and any Avalara side migration should be reviewed and managed directly with Avalara.

Before You Change the Avalara Connection

Confirm the following in Avalara before updating your Recurly tax settings.

Requirement Why it matters
The new AvaTax account is active and contracted directly with Avalara. Recurly can only connect successfully if the Avalara account is ready for production use.
The correct Avalara company exists and the company code is final. The company code entered in Recurly must match the Avalara company that should receive transactions.
Tax jurisdictions are configured in Avalara. Jurisdiction setup controls where Avalara calculates tax. Ideally, enable jurisdictions only when the new account has been connected and validated.
The Avalara company address matches the Recurly Business Entity company address. Recurly sends the Business Entity company address to Avalara as the origin address.
Tax codes, entity use codes, exemption handling, and jurisdiction rules are configured. These Avalara-side settings influence taxability, exemption behavior, and jurisdiction-specific calculation results.

Update the Avalara Settings in Recurly

  1. In the Recurly Admin Console, go to Configuration > Taxes.
  2. Open Avalara AvaTax.
  3. Select Configure.
  4. Update the Avalara credentials and company code for the new Avalara account or company.
  5. Run Test Configuration to confirm Recurly can connect successfully.
  6. Review test results before relying on the new connection for production transactions.
Important: Do not treat a saved credential update as a completed migration. Always run the test configuration and validate tax behavior before the cutover is considered complete.

If Multiple Recurly Sites Use Avalara

If the same Avalara account is used by more than one Recurly site, use a separate Avalara company for each Recurly site whenever possible.

Recurly sends the Recurly invoice number to Avalara as the document code. If multiple Recurly sites send transactions into the same Avalara company, duplicate invoice document codes can occur if invoice numbering overlaps between sites.

Best practice: Map each Recurly site to its own Avalara company code to reduce the risk of duplicate document codes and to keep reporting cleaner.

What About Historical Avalara Data?

Switching the Recurly integration to a new Avalara account does not require Recurly to export data for the integration change itself. However, you should decide how to handle historical tax records before the cutover.

You will need to work with Avalara directly if you need to move or preserve:

  • Prior Avalara tax documents
  • Committed returns
  • Customer exemption records
  • Reporting history
  • Historical compliance records

Validation Checklist

Before considering the migration complete, confirm:

  • Recurly's Avalara test configuration succeeds.
  • The Avalara company code in Recurly matches the intended company in Avalara.
  • The Recurly Business Entity company address matches the expected Avalara origin address.
  • Tax jurisdictions and taxability rules are configured in the new Avalara account.
  • Exemption handling and entity use codes are set up, if your business uses them.
  • Any historical reporting or compliance data has been handled with Avalara.

When to Pause the Cutover

Pause the migration and resolve the issue first if:

  • The new Avalara account or company is not active.
  • The company code is uncertain or may still change.
  • Recurly's test configuration fails.
  • Tax jurisdictions, tax codes, exemptions, or entity use codes have not been configured.
  • The same Avalara company will receive transactions from multiple Recurly sites without a document-code plan.
  • Your finance or tax team still needs historical Avalara data migrated or preserved.

For general setup details, please see Recurly's Avalara documentation: Avalara.

Related articles

Comments

0 comments

Please sign in to leave a comment.