Avalara Tax Python SDK

26.3.2 · active · verified Sat Apr 11

The Avalara Tax Python SDK provides an interface to the Avalara AvaTax REST V2 API for calculating sales tax, managing tax profiles, and handling compliance. It offers functionalities for transaction processing, nexus management, and address validation. The library is actively maintained with frequent releases, often monthly, reflecting updates to the underlying AvaTax API.

Warnings

gotcha Always explicitly set the `environment` parameter in `AvalaraClient` to either 'sandbox' or 'production'. Failing to do so can lead to unintended API calls against the wrong environment (e.g., live transactions during testing or vice-versa), or relying on an implicit default that might change across SDK versions.
Fix: When initializing, ensure `AvalaraClient(..., environment='sandbox')` or `environment='production'` is used.
breaking The SDK's versioning (e.g., `26.x.x`) primarily tracks updates to the underlying Avalara AvaTax API. Frequent API enhancements can introduce new required fields, modify existing model structures (e.g., `TransactionModel`, `AddressModel`), or change endpoint behaviors. Not updating the SDK or reviewing release notes can lead to API validation errors or unexpected results if your local code is out of sync with recent API changes.
Fix: Regularly update the SDK (`pip install --upgrade avalara`). Carefully review the official release notes for the Python SDK and Avalara API documentation for changes to model structures, required parameters, or new functionalities, especially when encountering validation errors.
gotcha Avalara API models (e.g., `TransactionModel`, `LineItemModel`, `AddressModel`) can be deeply nested and require specific data types. While the SDK often accepts Python dictionaries that map to these models, incorrect nesting, missing required fields, or wrong data types are common sources of API validation errors. These errors are typically reported by the API itself.
Fix: Consult the AvaTax API documentation for the specific endpoint's request schema. For complex structures, thoroughly validate your dictionary payloads against the expected schema or consider explicitly instantiating models from `avalara.models` for better IDE auto-completion and type checking.
deprecated Older versions of the SDK (prior to approximately v24.x.x) might have used different client classes or authentication methods (e.g., `BasicAuthClient`). The current `AvalaraClient` provides a unified and simplified approach. Using older patterns with new SDK versions can lead to import errors or authentication failures.
Fix: Update your SDK to the latest version (`pip install --upgrade avalara`) and refactor client initialization to use `AvalaraClient(username=..., password=..., app_name=..., app_version=..., machine_name=..., environment=...)`.

Install

pip install avalara Install latest version

Imports

AvalaraClient
```
from avalara import AvalaraClient
```
TransactionModel
```
from avalara.models import TransactionModel
```
Used for detailed tax calculations, often passed as a dictionary payload to client methods.
AvaTaxException
```
from avalara.exceptions import AvaTaxException
```
Base exception for handling API errors returned by the Avalara service.

Quickstart

Initializes the Avalara client using credentials loaded from environment variables and demonstrates a basic connectivity check with the `ping` API. It then shows how to create a simple sales tax transaction, passing a dictionary payload that maps to the `TransactionModel` structure.

import os
from avalara import AvalaraClient

# --- Configuration (recommended via environment variables) ---
# Replace 'YOUR_...' with actual credentials or ensure environment variables are set
username = os.environ.get('AVALARA_USERNAME', 'YOUR_USERNAME')
password = os.environ.get('AVALARA_PASSWORD', 'YOUR_PASSWORD')
app_name = os.environ.get('AVALARA_APP_NAME', 'MyApp')
app_version = os.environ.get('AVALARA_APP_VERSION', '1.0')
machine_name = os.environ.get('AVALARA_MACHINE_NAME', 'MyMachine')
environment = os.environ.get('AVALARA_ENVIRONMENT', 'sandbox') # 'sandbox' or 'production'

if username == 'YOUR_USERNAME':
    print("Warning: Please set AVALARA_USERNAME and other env vars for a real test.")

client = AvalaraClient(
    username=username,
    password=password,
    app_name=app_name,
    app_version=app_version,
    machine_name=machine_name,
    environment=environment
)

# --- Example: Ping API (check connectivity) ---
try:
    ping_result = client.ping()
    print(f"Ping successful: {ping_result.message}")

    # --- Example: Create a simple tax transaction (using a dictionary payload) ---
    transaction_payload = {
        'lines': [
            {
                'itemCode': 'PC0001',
                'quantity': 1,
                'amount': 100.00
            }
        ],
        'type': 'SalesOrder',
        'companyCode': 'DEFAULT',
        'customerCode': 'ABC',
        'date': '2024-01-01',
        'commit': False,
        'addresses': {
            'singleLocation': {
                'line1': '123 Main St',
                'city': 'Irvine',
                'region': 'CA',
                'postalCode': '92612',
                'country': 'US'
            }
        }
    }

    transaction_result = client.create_transaction(model=transaction_payload)
    print(f"Transaction created successfully. Total tax: {transaction_result.totalTax}")
    for line in transaction_result.lines:
        print(f" - Item {line.itemCode}: Tax {line.tax}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →