Chapter 1.5 - Best Practices


Use Customer Portal Sandbox to test:

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
  • 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 supports addresses in the United States and US Territories
    • Supports street-level lookup
  • 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 supports addresses in the United States and US Territories
    • Supports street-level lookup
    • 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
    • Doesn't support street-level lookup
    • Communications PCodes are updated monthly

Customizing Transactions

Increase Your Throughput

  • Limit your Line Item count per transaction
    • Make more CalcTaxes requests with fewer line items in each request to increase performance throughput
    • It is better to send 300 CalcTaxes requests containing 1,000 line items in each call than to send 30 CalcTaxes 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 bill run or invoice
  • Use a unique Document Code (doc) for each group of transactions (for example, a GUID)
  • Use a generic Document Code (doc), such as "QUOTE", for transactions not intended to be be committed
  • The Commit flag (cmmt) can be set for each transaction
  • Use the Commit endpoint (/api/v2/afc/commit) to commit or uncommit a Document Code once the transaction has been submitted
  • All committed transactions are locked at the end of the month and can't be uncommitted or changed

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