Avalara Avatax REST SDK for iOS now available!

If you’re building mobile related retail applications or extensions to your ERP/Ecommerce platforms on iOS for the iPhone or iPad, then you’re in luck. We just completed the iOS Software Development Kit that allows you to easily connect to Avalara’s Avatax API. The SDK comes as a static library that you can link to your iOS projects. For REST de/serialization, we’ve used a 3rd party library called JSONModel which simplifies data transformation from object model to JSON (and back). We’ve included that into the project as well as the full source code under the Apache 2.0 license.

You can download the SDK and others from our Sample Code Library.  Please feel free to try it out and give us some feedback.

 

Prompting users for certificate information with the AvaTax Certs API

The AvaTax Certs product is a stand-alone exemption certificate management product that can be used in conjunction with the AvaTax Calc product. The Certs product allows a company to track exempt customers, initiate automated correspondence to request certificate information from those customers, and track and manage the resulting exemption certificates. All valid certificates created/recorded in the AvaTax Certs product sync over to the AvaTax Calc product as well – once a customer has a valid exemption certificate in Certs, they will automatically be tax exempt for your tax calculations.

There is a RESTful API to interact with the AvaTax Certs objects. That API documentation is password-protected. If you have an AvaTax Certs portal account, that same credential set will grant you access to the API documentation.

Note that the AvaTax Certs product is currently being combined with the CertCapture product, but this article uses the resource terminology specific to the AvaTax Certs API.

If you are interested in flagging your customers as tax exempt within the AvaTax Calc product (and not in using an additional certificate management product), take a look at this summary of managing exempt customers.

Okay, now let’s get down to brass tacks. You have a customer who is buying things on your website and wants to let you know that they are tax exempt. Here’s a diagram of the recommended workflow (with API calls):

AvaTax Certs Workflow

*If you’re using the AvaTax Calc product to calculate tax, it will reflect the existing exempt status for the customer.

** The wizard URL is just www.vcert.com/<certificate-request-id>, where the certificate request ID is the unique request identifier returned in the Org-Requests POST response. Note that if a customer already has an open certificate request, Org-Requests POST will return an error, and that existing request ID can be retrieved with Org-Requests GET.

This workflow will cover the following starting cases:

  • The customer record does not yet exist.
  • The customer record exists, but has no certificates and no open certificate request.
  • The customer record exists and has an open certificate request.
  • The customer record exists and has one or more expired/revoked certificates and no open certificate request.
  • The customer record exists and has one or more valid certificates.

Once a customer has filled out their exemption information, their order can be processed per your business use case.

Handling Java SSL Certificate Exception

If you are trying to make an HTTPS call to the AvaTax web service from a WebSphere Message Broker  and recieve an exception message similar to below, it is likely that the Message Broker is unable to build the entire certificate path. The Message Broker “keystore” must have all of the certificates in the “chain” of CA’s.

javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by OU=Class 3 Public Primary Certification Authority, O=”VeriSign, Inc.”, C=US is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error

One way to verify that all of the required certificates are in your keystore is using the “keytool” from the bin directory of the interface in use.

  1. Start an Administrator Command Prompt.
  2. Navigate to the bin directory of the API method you are using.
  3. Type keytool –list and review the certificates stored. You should see at least one Verisign certificate authored by Avalara with an expiration date greater than the current date.
  4. If not, you may need to recreate the keystore with ‘keytool’ using the “genkey” option and re-import your application certificates if any of the components of the certificate chain are missing or out of date.

Search http://www-01.ibm.com/support/ for “keystore” or “keytool” or “genkey” for more information.

Note:  If you are using a Microsoft Windows environment, Certificate Manager (CertMgr) can be accessed via your devices Management Console. You will need administrative rights to use this tool.

Testing Address Errors

When you’re testing your integration, it’s always a good idea to figure out how you’re going to handle errors. Not all errors from our system are bad – some just mean a user has entered an invalid address (perhaps by making a typo!) – and your system should react accordingly. These address-related errors are to be expected in normal use of your connector.

Sometimes it can be challenging to create this use case on purpose: our system is very good at validating addresses and calculating tax accordingly (albeit at lower precision levels). In fact, due to customer demand, we recently updated the service to allow tax calculation on zip5. This is not always the most accurate tax, but if your business only collects zip codes, we’ll give you something to work with.

If you’re looking for an error case, here are some good ways to create one:

Let’s start with a real, valid address. Our address is:
100 Ravine Ln
Bainbridge Island, WA 98110

By changing enough elements, we eventually return JurisdictionNotFoundError in the GetTaxResult. Let’s start with the address line:

1000 Ravine Ln
Bainbridge Island, WA 98110

There is no 1000 on Ravine Ln, but that alone won’t fail tax calculation because city, state and zip is enough.

1000 Ravine Ln
Bainbrid, WA 98110

I truncated the city too, but even that still returns tax because state and zip is sufficient to determine a tax region.

1000 Ravine Ln
Bainbrid, WA 43256

When I change the zip, it returns the error, because there just aren’t enough matching elements for the system to find the location. Finally, our error! By moving through each address element in turn, we get a better picture of how Avatax uses elements in the tax calculation, and its threshold for bad addresses. Of course, if you want to just go for it, you can always generate an error by making sure that none of your address elements match:

521 Totally Bogus Parkway
Tacoma, CA 11111

Reflecting MDET

At the beginning of 2013, a new federal-level excise tax was introduced for some medical devices. If you have clients that need to reflect this tax, make sure you’re doing the following:
1. Allow clients to pass a product tax code.
2. Allow clients to assign an Entity/Use Code (CustomerUsageType) to their customers.

The combination of product tax code and customer entity/use code allows your client to trigger specific rules in their company profile, and calculate this tax. If you’re using service version 13.1 or later, you can parse out this tax from your GetTaxResult as well – it will come across as a TaxDetail element with TaxType of Excise and JurisType of Country.

Updates to REST tax/get POST with 13.3. release

Some long-awaited additional parameters have been added to the tax/get POST request with the recent 13.3 release. These parameters are now available on both development and production for all clients using the REST API. With this update, the REST API is now in full best-practice parity with our SOAP API. For more information, see the tax/get POST documentation.

  • PosLaneCode
  • Client
  • BusinessIdentificationNo
  • TaxOverride

Global Certification

As we expand our global calculation capabilities, we’ve been talking about what’s required to create a truly compliant VAT calculation. Depending on your business requirements, you may want to think about global certification. We only have the G1 and G2 certification available right now, but we’ll be adding the tertiary address required for G3 certification soon!

Certified for AvaTax Global 1 (G1)

Global 1 certification includes functionality to calculate transaction tax (VAT) in the following use cases:

  1. Transaction originating in the United States shipping to any country currently supported by Avalara AvaTax service
  2. Transaction originating in Canada shipping to any country currently supported by Avalara AvaTax service
  3. Intra-country transaction for any country supported by Avalara AvaTax service

Requirements:

  • GetTax request address includes Country Code
  • GetTax request includes CurrencyCode

Certified for AvaTax Global 2 (G2)

Global 2 certification includes functionality to calculate transaction tax (VAT) in the following use cases:

  1. Transaction originating in an European Union (EU) country shipping to a non-EU country supported by the Avalara AvaTax service
  2. Transaction originating in the United States shipping to any country currently supported by Avalara AvaTax service
  3. Transaction originating in Canada shipping to any country currently supported by Avalara AvaTax service
  4. Intra-country transaction for any country supported by Avalara AvaTax service

Requirements:

  • GetTax request includes BusinessIdentificationNo (VAT registration ID)
  • GetTax request address includes Country Code
  • GetTax request includes CurrencyCode

    Certified for AvaTax Global 3 (G3)

    Global 3 certification includes functionality to calculate transaction tax (VAT) in the following use cases:

    1. Transaction originating in an EU country shipping to an EU country
    2. Transaction originating in an EU country shipping to a non-EU country supported by the Avalara AvaTax service
    3. Transaction originating in the United States shipping to any country currently supported by Avalara AvaTax service
    4. Transaction originating in Canada shipping to any country currently supported by Avalara AvaTax service
    5. Intra-country transaction for any country supported by Avalara AvaTax service

    Requirements:

    • GetTax request includes Third Address records (supports triangulation)
    • GetTax request includes BusinessIdentificationNo (VAT registration ID)
    • GetTax request address includes Country Code
    • GetTax request includes CurrencyCode