Avalara Developer Network Developer avaTax

Test

Integration Testing

When you run tests (automatically or manually), take care to call the AvaTax service only when needed. We don't have a way of distinguishing between test calls and actual live calculations (since they all return real tax calculations from us), so they are all included in the calculation of your billable transactions. In tests where a live tax calculation is required (for example, to check if the service is available or if your credentials are correct), there is no replacement for an actual call to the API. For the majority of cases, however, we recommend that you stub out the AvaTax API calls. This will save you on both the time it takes to run your unit and integration tests (and non-tax functional tests), and the number of transactions you consume.

Functional Testing Scenarios

Depending on the scope of your Avalara AvaTax Sales Tax API integration and your business practice, your exact test cases may vary: if you're building a custom connector that will just be used for a single client, you might not need to manage credentials through a UI. For development partners building connectors, however, these features become essential. The following is a full list of the features we look for in an integration.

Use Case Expected Outcome Documentation
Pull up the AvaTax Administration panel/page in your application Administrative user should be able to view/modify:
  • AvaTax Account Number
  • AvaTax License Key
  • Service URL (will they be connecting to our development or production environment?)
  • AvaTax Company Code
They should also be able to:
  • Disable AvaTax tax calculation (independently of address validation)
  • Disable AvaTax address validation (independently of tax calculation) altogether, or by country
  • Make a test connection to the AvaTax service using account credentials, but independent of tax calculation and address validation.
Logins and Resources

Utility and Configuration Screen (Video)
Look at the touch points in your customer record You should be able to identify:
  • What will be transmitted to AvaTax as the CustomerCode
  • Which addresses (if any) on the customer record will be used for tax calculation, and how they can be validated
  • How the customer can be marked as tax exempt
  • If you have integrated to the AvaTax CertCapture product, the touch points for customers and exemption requests
Customer Record (Video)
Look at the touch points in your item record (inventory maintenance) You should be able to identify:
  • What will be transmitted to AvaTax as the Item Code
  • What will be transmitted to AvaTax as the Item Description
  • How the item taxability is controlled (what will be transmitted to AvaTax as Tax Code)
Item Record (Video)
Run a test transaction with more than one line, where each line has more than one quantity.
  • Depending on your integration scope, the transaction should be saved to the AvaTax Website
  • The lines should transmit the specified quantity
  • The lines should show extended amount
  • Any shipping/miscellaneous charges should be reflected as additional line items in the transaction record on the AvaTax Website
  • All information identified above in the customer record and item record should be saved in the transaction
Transaction Lifecycle (Video)
Process a transaction for a tax exempt customer The transaction should be recorded in AvaTax with the identified tax exemption indicator Handling Tax Exempt Customers

Exempt Customer (Video)
Process a partial return (for a taxable customer, and then a tax exempt customer), and then another partial return associated with the same order/invoice. The return should be recorded on the AvaTax Website with the following:
  • Negative (extended) amounts, and positive quantities reflecting the returned quantities and amounts, thus calculating negative liability
  • Document Date of the date when the return was processed, but a Tax Date that reflects the date of the original invoice (note: this is not possible in the REST API v1)
  • Shipping charges (etc.) should be recorded on this transaction (or not) as per business practice
  • All customer and item information should be the same as on the original transaction
Product Returns
Take a transaction through the entire document lifecycle of an order/invoice etc. The transaction should follow the lifecycle logically in the AvaTax Website, ending with a committed transaction. Sample Workflows

Transaction Lifecycle (Video)
Take a return through its entire document lifecycle. The transaction should follow the lifecycle logically in the AvaTax Website, ending with a committed return transaction. Sample Workflows
If applicable, void/delete a transaction (if possible, both an invoice and a credit) in your application The transaction record in AvaTax should reflect a "Voided" document status. Cancel Transactions

Voided Invoice (Video)

Tax Compliance Edge Cases:

Sales tax calculation can create a number of different interesting edge cases. Make sure your connector's calculation agrees with a calculation on the AvaTax Website for the following use cases:

  • An order with some taxable items (with no tax code, or a taxable tax code), some nontaxable items(using tax code NT, or another nontaxable code), and a shipping line (using tax code FR)
    • In California, the shipping line should be nontaxable
    • In Alabama, the shipping line should be taxable
    • In Arkansas, the shipping line should be partially taxable
  • An order in Tennessee with a line item with a quantity of one and an amount above $1600 should match the calculation in the AvaTax Website (pay particular attention to the jurisdictional breakout).
  • An order in any state with Entity/Use Code (CustomerUsageType) of N (indicating a Local Government exemption) should not be fully exempt from sales tax.