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 name space, or your python script.

 from avalara import AvataxClient      

Now we are ready to 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 four string parameters, in squence they are app_name(required), app_version(required), machine_name(optional), and environment(required). The app_name, app_version, machine_name will be used to construct the Client Header associated with each call made by this client. It will be returned within 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 AvaTax service.

If you are 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 Customer Account Manager

Ping the service

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

response = client.ping()
                     
# to view respnse 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 calls made using this SDK will be Request object, which contains 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 those information provided by you with your account. To find out if a method requires authentication, visit our API Reference page.

To add credential on the current client object:

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

The add_credential method will hash your username/password, or account_id/license_key pair and attach to every call made by your client object, meaning you only have to add credential once to each client you prepare to use.

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

To create a transaction using your client object

Now 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. Which you will fill out to 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, simply visit this code page

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

Use transaction builder

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

First import the transaction builder constructor into your name space:

from avalara.transaction_builder import TransactionBuilder 

Then, let's create a transaction builder object:

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

The builder takes four required parameters, in sequence they are

• The client object

• Company name(created through AvaTax portal or by calling CreateCompany API)

• The type of transaction, a full list of options.

• The customer code, an unique code identifying the customer that requested this transaction.

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

For a fulll list of transaction builder methods available and the parameters they take in, visit the code page

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 build so far, and return back the response.

Setup 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 simply 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/void dummy transactions on the account to verify functionalities.