• Previous
• Next Chapter

Testing

Use Customer Portal Sandbox to test:

• Changes to your Communications REST v2 integration
• Transaction customizations
• New client profiles
• Upcoming bill runs

Jurisdiction Determination

Picking the correct jurisdiction is critical because taxes are location-specific. REST v2 provides different ways to determine the jurisdiction:

• Populate a location on the Invoice and Line Item.
• Set BillTo (bill).
• If applicable, set the Origination (from) and Termination. (to) locations
• See Jurisdiction Determination for more information.
• Use the Geo REST Lookup endpoint.
• Perform lookups separately on a monthly or quarterly basis.
• Store the PCode (pcd) and Incorporated flag (inc) returned in the Geocode Result for the address or latitude/longitude requested.
• Up to 1,000 addresses are supported in a single geocode request.
• Communications PCodes are updated monthly.
• Communications geocoded addresses are updated quarterly.
• Only addresses in the United States and US Territories are supported.
• Street-level lookup is supported.
• Use Geo Batch for high-volume geocoding requests.
• Upload a CSV containing your address or latitude/longitude geocoding requests.
• Limit CSV files to 200k records to reduce processing time and loss of information in the event of an error.
• Download and export the results to your database.
• Call the Geo Batch Status endpoint (/api/v2/geo/batch/status/{processId}) every minute in order to retrieve results as quickly as possible.
• Geo Batch Status endpoint download links are only active for 1 minute - reprocess the endpoint to retrieve a new valid link.
• 5,000 consecutive errors causes the entire batch to fail immediately.
• Embed a geocode request within the transaction by setting geo = true within a Location.
  • Usage of the embedded geocode lookup is only to be used if you have very low transaction counts.
  • Only addresses in the United States and US Territories are supported.
  • Street-level lookup is supported.
  • This adds a considerable amount of time to the calculation throughput.
• Use PCode Lookup endpoint.
• Perform lookups separately on a monthly or quarterly basis.
• Store the PCode (pcd) returned in the Zip Lookup Result for the location requested.
• Street-level lookup is not supported.
• Communications PCodes are updated monthly.

Customizing Transactions

• Observe the hard limits per request:
  • 1,000 invoices (inv)
  • 10,000 line items (itms)
• See Customizing Transactions:
  • Use client profiles to define account customizations.
  • Modify transactions to meet your business needs.
• Set the Request Config (cfg) options to customize your response output:
  • Utilize the Reporting Information fields to easily tie data from the billing application to Reporting.
  • Configure the amount of information returned in the response using the Return Non-Billable Taxes (retnb) flag and the Return Extended Data (retext) flag. For more information, see Request Config.

Increase Your Throughput

• Limit your Line Item count per transaction.
• Make more CalculateTaxes requests with fewer line items in each request to increase performance throughput.
• It is better to send 300 CalculateTaxes requests containing 1,000 line items in each call than to send 30 CalculateTaxes requests with 10,000 line items.
• Use Customer Portal Sandbox to try out different scenarios and find your ideal line item count.
• Use multi-threading to perform multiple tax calculations asynchronously.
• Use multiple threads instead of a single thread.
• Consider the performance of your application servers when determining the number of threads to use.
• Use Customer Portal Sandbox to identify your ideal thread count.
• Summarize Call Detail Record (CDR) data.
• Consider summarizing CDR data over a period of time when volume is extremely high.
• Submit the summarized CDR data for taxation.

Using Commit and Uncommit

The Commit process groups transactions by a Document Code (doc) and indicates if the transaction group should be included in compliance reporting (cmmt).

• Group transactions by invoice.
• Use a unique Document Code (doc) for each group of transactions (for example, a GUID).
• Use a metadata field, such as Invoice Number Reference (invn), to create an association between a Document Code and an invoice. This gives you the flexibility to uncommit Document Codes throughout the calendar month, effectively removing these transactions from your committed reports. It also helps reconcile data between your internal billing system and Avalara.
• Do not send a Document Code (doc) for transactions not intended to be be committed, such as quotes. Leave this field empty.
• Use the Commit endpoint (/api/v2/afc/commit) to commit or uncommit a Document Code once the transaction has been submitted. You cannot change the commit status of a Document Code through the CalculateTaxes API.
• All committed transactions are locked at the end of the calendar month and cannot be uncommitted or changed. You must submit an adjustment to reclaim taxes in future filing periods.

Flexibility for the Future

Pass the client_id and client_profile_id in the header.

• Passing the client_id and client_profile_id fields allows for future support of multiple profiles and clients.
• It is much easier to include these fields early in your development effort than add the fields later when it becomes necessary.
• Use 0 for (the default System profile) for client_profile_id if you don't have a customized client profile.

• Previous
• Next Chapter