Install & Compatibility
Where this runs
tested against v26.8.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.372s · 23.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.0s · import 0.372s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AvataxClient
✓ from avalara import AvataxClient
✗ from avalara import AvalaraClient
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}")
Debug
Known issues
gotchaAlways 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.fixWhen initializing, ensure `AvalaraClient(..., environment='sandbox')` or `environment='production'` is used.
affects: All versions
breakingThe 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.fixRegularly 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.
affects: All versions, particularly when upgrading across minor increments (e.g., 25.x.x to 26.x.x)
gotchaAvalara 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.fixConsult 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.
affects: All versions
deprecatedOlder 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.fixUpdate 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=...)`.
affects: < 24.x.x (roughly, review specific client documentation for exact transitions)
Upgrade
Version history
26.8.3latest on PyPI · released Aug 24, 2026
Audit
Dependencies
requestsrequiredHTTP client for API communication
certifirequiredSSL certificate bundling
python-dateutilrequiredDate/time parsing utilities for models
urllib3requiredHTTP client dependency