# Chapter 1.5 - Best Practices Source: https://developer.avalara.com/products/communications/integration-guides/dev-guide_rest_v2/getting-started/best-practices/ - [Previous](/communications/dev-guide_rest_v2/getting-started/demo-app/) - [Next Chapter](/communications/dev-guide_rest_v2/calculate-taxes/) ### Testing Use [Customer Portal Sandbox](https://communicationsua.avalara.net) to test: - Changes to your Communications REST v2 integration - [Transaction customizations](/communications/dev-guide_rest_v2/customizing-transactions/transaction-use-cases) - New [client profiles](/communications/dev-guide_rest_v2/customizing-transactions/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](/communications/dev-guide_rest_v2/reference/invoice) and [Line Item](/communications/dev-guide_rest_v2/reference/line-item). - Set [BillTo](/communications/dev-guide_rest_v2/reference/location) (`bill`). - If applicable, set the [Origination](/communications/dev-guide_rest_v2/reference/location) (`from`) and [Termination.](/communications/dev-guide_rest_v2/reference/location) (`to`) locations - See [Jurisdiction Determination](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/jurisdiction-determination/) for more information. - Use the [Geo REST](/communications/dev-guide_rest_v2/getting-started/environments-endpoints#jur_determine/) Lookup endpoint. - Perform lookups separately on a monthly or quarterly basis. - Store the PCode (`pcd`) and Incorporated flag (`inc`) returned in the [Geocode Result](/communications/dev-guide_rest_v2/reference/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](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch/) for high-volume geocoding requests. - [Upload](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch#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](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/geo-batch#status) endpoint (`/api/v2/geo/batch/status/{processId}`) every minute in order to retrieve results as quickly as possible. - [Geo Batch Status](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/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](/communications/dev-guide_rest_v2/reference/location). - Usage of the embedded [geocode lookup](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/jurisdiction-determination/) 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](/communications/dev-guide_rest_v2/getting-started/environments-endpoints#jur_determine/) Lookup endpoint. - Perform lookups separately on a monthly or quarterly basis. - Store the PCode (`pcd`) returned in the [Zip Lookup Result](/communications/dev-guide_rest_v2/reference/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](/communications/dev-guide_rest_v2/reference/invoice/) (`inv`) - 10,000 [line items](/communications/dev-guide_rest_v2/reference/line-item/) (`itms`) - See [Customizing Transactions](/communications/dev-guide_rest_v2/customizing-transactions/): - Use [client profiles](/communications/dev-guide_rest_v2/customizing-transactions/client-profiles) to define [account customizations](/communications/dev-guide_rest_v2/customizing-transactions/account-customizations/). - [Modify transactions](/communications/dev-guide_rest_v2/customizing-transactions/transaction-use-cases) to meet your business needs. - Set the [Request Config (`cfg`)](/communications/dev-guide_rest_v2/reference/request-config) options to customize your response output: - Utilize the [Reporting Information fields](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/request-config#reporting) 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](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/request-config). ### Increase Your Throughput - Limit your **Line Item count** per transaction. - Make more [`CalculateTaxes` requests](/communications/dev-guide_rest_v2/calculate-taxes/) 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](https://communicationsua.avalara.net) 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](https://communicationsua.avalara.net) 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](/communications/dev-guide_rest_v2/commit-uncommit/) 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](/communications/dev-guide_rest_v2/commit-uncommit/commit-request) (`/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](/communications/dev-guide_rest_v2/calculate-taxes/). - 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](/communications/dev-guide_rest_v2/customizing-transactions/client-profiles/). - [Previous](/communications/dev-guide_rest_v2/getting-started/demo-app/) - [Next Chapter](/communications/dev-guide_rest_v2/calculate-taxes/)