{"id":2871,"library":"avalara","title":"Avalara Tax Python SDK","description":"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.","status":"active","version":"26.3.2","language":"en","source_language":"en","source_url":"https://github.com/avadev/AvaTax-REST-V2-Python-SDK","tags":["tax","ecommerce","finance","compliance","saas"],"install":[{"cmd":"pip install avalara","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"HTTP client for API communication","package":"requests","optional":false},{"reason":"SSL certificate bundling","package":"certifi","optional":false},{"reason":"Date/time parsing utilities for models","package":"python-dateutil","optional":false},{"reason":"HTTP client dependency","package":"urllib3","optional":false}],"imports":[{"symbol":"AvalaraClient","correct":"from avalara import AvalaraClient"},{"note":"Used for detailed tax calculations, often passed as a dictionary payload to client methods.","symbol":"TransactionModel","correct":"from avalara.models import TransactionModel"},{"note":"Base exception for handling API errors returned by the Avalara service.","symbol":"AvaTaxException","correct":"from avalara.exceptions import AvaTaxException"}],"quickstart":{"code":"import os\nfrom avalara import AvalaraClient\n\n# --- Configuration (recommended via environment variables) ---\n# Replace 'YOUR_...' with actual credentials or ensure environment variables are set\nusername = os.environ.get('AVALARA_USERNAME', 'YOUR_USERNAME')\npassword = os.environ.get('AVALARA_PASSWORD', 'YOUR_PASSWORD')\napp_name = os.environ.get('AVALARA_APP_NAME', 'MyApp')\napp_version = os.environ.get('AVALARA_APP_VERSION', '1.0')\nmachine_name = os.environ.get('AVALARA_MACHINE_NAME', 'MyMachine')\nenvironment = os.environ.get('AVALARA_ENVIRONMENT', 'sandbox') # 'sandbox' or 'production'\n\nif username == 'YOUR_USERNAME':\n    print(\"Warning: Please set AVALARA_USERNAME and other env vars for a real test.\")\n\nclient = AvalaraClient(\n    username=username,\n    password=password,\n    app_name=app_name,\n    app_version=app_version,\n    machine_name=machine_name,\n    environment=environment\n)\n\n# --- Example: Ping API (check connectivity) ---\ntry:\n    ping_result = client.ping()\n    print(f\"Ping successful: {ping_result.message}\")\n\n    # --- Example: Create a simple tax transaction (using a dictionary payload) ---\n    transaction_payload = {\n        'lines': [\n            {\n                'itemCode': 'PC0001',\n                'quantity': 1,\n                'amount': 100.00\n            }\n        ],\n        'type': 'SalesOrder',\n        'companyCode': 'DEFAULT',\n        'customerCode': 'ABC',\n        'date': '2024-01-01',\n        'commit': False,\n        'addresses': {\n            'singleLocation': {\n                'line1': '123 Main St',\n                'city': 'Irvine',\n                'region': 'CA',\n                'postalCode': '92612',\n                'country': 'US'\n            }\n        }\n    }\n\n    transaction_result = client.create_transaction(model=transaction_payload)\n    print(f\"Transaction created successfully. Total tax: {transaction_result.totalTax}\")\n    for line in transaction_result.lines:\n        print(f\" - Item {line.itemCode}: Tax {line.tax}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"When initializing, ensure `AvalaraClient(..., environment='sandbox')` or `environment='production'` is used.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, particularly when upgrading across minor increments (e.g., 25.x.x to 26.x.x)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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=...)`.","message":"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.","severity":"deprecated","affected_versions":"< 24.x.x (roughly, review specific client documentation for exact transitions)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}