AvaTax SDK Python

Create a transaction

Import the AvataxClient from the avalara module

First thing to do is to import the AvataxClient constructor module to your namespace or your Python script.

 from avalara import AvataxClient      

Construct a client object

Create a new AvataxClient object:

client = AvataxClient('my test app', 
                       'ver 0.0', 
                       'my test machine',  
                      'sandbox')          

The client constructor takes 4 string parameters. In sequence, they are app_name(required), app_version(required), machine_name(optional), and environment(required). The app_name, app_version, and machine_name will be used to construct the Client Header associated with each call made by this client. It will be returned in the response object to help you keep track of the API calls.

The environment variable can be either "sandbox" or "production". They correspond to the two different environments for the AvaTax service.

If you're a regular or free trial customer, please use "production". If you don't have an account, you can sign up for a free trail account on our developer site. This will be a Production account as well.

If you wish to obtain a Sandbox account, please contact your account manager.

Ping the service

Now that we have a client object, we can ping the AvaTax REST V2 server to ensure connectivity.

response = client.ping()
                     
# to view response text            
print(response.text()) 
                    
# to view json version of the response            
print(response.json()) 
                    
# to view the status code           
print(response.status_code()) 
             
# to view the raw response          
print(response.raw())         

Note that the response from all REST API calls made using this SDK will be a Request object, which contains a status code, response text, raw JSON, and more information on the response.

Add credentials to your client object

Unlike ping, most methods in our REST V2 API requires you to be authenticated in order to associate information provided by you with your account. To find out if a method requires authentication, visit our API Reference page.

To add credentials on the current client object:

client = client.add_credentials('USERNAME/ACCOUNT_ID', 'PASSWORD/LICENSE_KEY')

The add_credentials method will hash your username/password, or account_id/license_key pair and attach it to every call made by your client object. This means you only have to add credentials once to each client you prepare to use.

To verify that you have added a valid credential, simply call the ping method again. You should see "authenticated": true in the response text.

Create a transaction using your client object

Now that our client object is authenticated, we can call the create_transaction method which calls the CreateTransaction API.

transaction_response = client.create_transaction(tax_document)            
 print(transaction_response.text())  
 tax_document = { 
               'addresses': {'SingleLocation': {'city': 'Irvine', 
                                                'country': 'US', 
                                                'line1': '123 Main Street', 
                                                'postalCode': '92615', 
                                                'region': 'CA'}}, 
               'commit': False, 
               'companyCode': 'DEFAULT', 
               'currencyCode': 'USD', 
               'customerCode': 'ABC', 
               'date': '2017-04-12', 
               'description': 'Yarn', 
               'lines': [{'amount': 100, 
                         'description': 'Yarn', 
                          'itemCode': 'Y0001', 
                          'number': '1', 
                          'quantity': 1, 
                          'taxCode': 'PS081282'}], 
               'purchaseOrderNo': '2017-04-12-001', 
               'type': 'SalesInvoice'}                    

The create_transaction method takes in a model. In Python, it's a dictionary type object in which you include all of your transaction information. In this case, we are using the TransactionModel. For information on other models use by AvaTax APIs, visit our information page here.

Use other methods

Like our SDKs in other languages, the Python SDK includes all methods offered by the AvaTax REST V2 API. To find a method corresponding to a specific API endpoint, visit this code page.

To learn more about integrating our REST API into your system, go to our developer guide that contains information on using the powerful features offered by our API.

Use the Transaction Builder tool

We realize that having to format the TransactionModel can be complicated and time consuming. Therefore, we created a tool called Transaction Builder to help you put together a transaction model and create it!

First, import the TransactionBuilder constructor into your namespace:

from avalara.transaction_builder import TransactionBuilder 

Then, create a TransactionBuilder object:

tb = TransactionBuilder(client, "DEFAULT", "SalesInvoice", "ABC")          

The builder takes 4 required parameters. In sequence, they are:

• The client object

• The company name (created through the AvaTax portal or by calling the CreateCompany API)

• The type of transaction (view the full list of options)

• The customer code (a unique code identifying the customer that requested this transaction)

Now, you can add transaction details to this object by using methods like with_address, with_line, and with_parameter.

For a full list of Transaction Builder methods available and the parameters they take, visit the code page on GitHub.

In the end, you may call the create method on your builder object, which will call the CreateTransaction API with the transaction model you have built so far and return back the response.

Set up test credentials

If you wish to run the integration and unit testings, you must store a pair of credentials in the current enviroment.

Add the following to the activate file in your environment and restart bash OR export them directly:

export SANDBOX_USERNAME='your_sandbox_username'          
export SANDBOX_PASSWORD='your_sandbox_password' 
                  
 # OR          
SANDBOX_ACCOUNTID='your_sandbox_account_id'          
SANDBOX_LICENSEKEY='your_sandbox_license_key'          

Note: Only Sandbox credentials should be used for testing as the test case will commit, adjust, or void test transactions on the account to verify functionalities.