{"id":9414,"library":"xero-python","title":"Xero Python SDK","description":"The Xero Python SDK (current version 11.0.0) is the official client library for interacting with the Xero API, primarily using OAuth2. It provides clients for various Xero API domains (e.g., Accounting, Identity) and is regularly updated to reflect changes in the Xero API specification, typically with minor releases for new features and patches for bug fixes.","status":"active","version":"11.0.0","language":"en","source_language":"en","source_url":"https://github.com/XeroAPI/xero-python","tags":["xero","accounting","api","oauth2","financial"],"install":[{"cmd":"pip install xero-python","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Main client for API configuration and token management.","symbol":"ApiClient","correct":"from xero_python.api_client import ApiClient"},{"note":"Used to configure the API client, e.g., base URL.","symbol":"Configuration","correct":"from xero_python.api_client import Configuration"},{"note":"API clients are now located in sub-modules corresponding to Xero API domains. This changed in v10.0.0.","wrong":"from xero_python import AccountingApi","symbol":"AccountingApi","correct":"from xero_python.accounting import AccountingApi"},{"note":"Used for managing connections and retrieving tenant IDs.","symbol":"IdentityApi","correct":"from xero_python.identity import IdentityApi"},{"note":"Models for specific API domains are in `xero_python.models.<domain>`.","symbol":"Contact","correct":"from xero_python.models.accounting import Contact"}],"quickstart":{"code":"import os\nimport json\nfrom xero_python.accounting import AccountingApi\nfrom xero_python.identity import IdentityApi\nfrom xero_python.api_client import ApiClient, Configuration, ApiException\n\n# IMPORTANT: In a real application, you would implement the full OAuth2 flow\n# to obtain and refresh tokens securely. This example assumes you have\n# a valid access token, refresh token, and tenant ID. \n# NEVER hardcode secrets or tokens in production code.\n\n# Load your Xero API credentials from environment variables\nCLIENT_ID = os.environ.get(\"XERO_CLIENT_ID\", \"YOUR_CLIENT_ID\")\nCLIENT_SECRET = os.environ.get(\"XERO_CLIENT_SECRET\", \"YOUR_CLIENT_SECRET\")\nREFRESH_TOKEN = os.environ.get(\"XERO_REFRESH_TOKEN\", \"YOUR_REFRESH_TOKEN\")\nACCESS_TOKEN = os.environ.get(\"XERO_ACCESS_TOKEN\", \"YOUR_ACCESS_TOKEN\") # Often short-lived\nTENANT_ID = os.environ.get(\"XERO_TENANT_ID\", \"YOUR_TENANT_ID\") # Specific Xero organisation ID\n\n# Initialize Xero API client configuration\nconfig = Configuration()\n# config.host can be set for specific regions if needed, e.g., 'https://api.xero.com' (default)\n\napi_client = ApiClient(config)\n\n# Set the OAuth2 configuration for token management (essential for refresh)\napi_client.set_oauth2_config(\n    client_id=CLIENT_ID,\n    client_secret=CLIENT_SECRET,\n    tenant_id=TENANT_ID # This is the Xero Organisation ID you want to interact with\n)\n\n# Manually set an initial token set (for demonstration purposes)\n# In a real app, you'd load this from secure storage and refresh as needed.\ntoken_set = {\n    \"access_token\": ACCESS_TOKEN,\n    \"refresh_token\": REFRESH_TOKEN,\n    \"expires_at\": 0 # Set to 0 to force immediate refresh if ACCESS_TOKEN is dummy/expired\n}\napi_client.set_token_set(json.dumps(token_set))\n\n# --- Token Refresh (Crucial for long-lived applications) ---\n# The SDK automatically tries to refresh if token_set.expires_at is in the past\n# when making an API call. For explicit control, you might call:\ntry:\n    api_client.refresh_token_set(token_set[\"refresh_token\"])\n    # After refresh, the token_set in api_client is updated.\n    # You should persist this new token_set securely.\n    # print(\"Token refreshed successfully.\")\nexcept ApiException as e:\n    print(f\"Error refreshing token: {e.body}\")\n    exit() # Cannot proceed without a valid token\n\n# Initialize the Accounting API client\naccounting_api = AccountingApi(api_client)\n\ntry:\n    # Example: Get the first 5 contacts\n    contacts = accounting_api.get_contacts(_page=1, _limit=5)\n\n    if contacts.contacts:\n        print(\"Successfully retrieved contacts:\")\n        for contact in contacts.contacts:\n            print(f\"- {contact.name} (ID: {contact.contact_id})\")\n    else:\n        print(\"No contacts found.\")\n\nexcept ApiException as e:\n    print(f\"Xero API Error: Status {e.status}, Body: {e.body}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This example demonstrates how to initialize the Xero Python SDK and make a simple API call (getting contacts), assuming you have already obtained an OAuth2 refresh token, access token, client ID, client secret, and a specific Xero organisation's tenant ID. In a real application, the OAuth2 authorization flow would be executed to obtain these tokens and they should be stored securely and refreshed automatically."},"warnings":[{"fix":"Migrate your authentication flow to OAuth2 and update all API client and model imports. Consult the official migration guide for detailed steps.","message":"Version 10.0.0 introduced major breaking changes, including the complete removal of OAuth1 support and a full rewrite of the SDK's internal structure.","severity":"breaking","affected_versions":"10.0.0+"},{"fix":"Implement the full OAuth2 Authorization Code Grant flow, including handling the redirect URL and state parameter, typically using a web framework like Flask (see official examples).","message":"The SDK's OAuth2 flow for web applications requires managing state and handling callbacks to securely obtain tokens. It's not a simple client_credentials grant.","severity":"gotcha","affected_versions":"All versions (OAuth2)"},{"fix":"After obtaining a refresh token, store it securely. Use `api_client.refresh_token_set()` to get a new access token and update the entire token set in your persistent storage.","message":"Access tokens are short-lived. Long-lived applications must implement robust refresh token management, including persisting the new token set after each refresh.","severity":"gotcha","affected_versions":"All versions (OAuth2)"},{"fix":"After successful authentication, use `IdentityApi().get_connections()` to list the organisations the user has connected. Extract the desired `tenant_id` from this list and set it using `api_client.set_tenant_id(tenant_id)`.","message":"All API calls require a `tenant_id` (representing a specific Xero organisation). This ID is not part of the initial token set and must be retrieved separately.","severity":"gotcha","affected_versions":"All versions (OAuth2)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your access token is valid and refreshed if necessary. Verify the `tenant_id` is correctly set on the `ApiClient` instance. Check the scopes requested during authentication match the API call.","cause":"The provided access token is invalid, expired, or the `tenant_id` is incorrect/missing for the requested scope.","error":"xero_python.exceptions.ApiException: (401) Reason: Unauthorized"},{"fix":"Update your imports. The main API clients are now specific to domains, e.g., `from xero_python.accounting import AccountingApi`. The `Xero` class no longer exists.","cause":"Attempting to use an old SDK import pattern or class name from versions prior to 10.0.0.","error":"AttributeError: module 'xero_python' has no attribute 'Xero'"},{"fix":"Ensure the token set is stored and loaded as a JSON string (e.g., from a file or database) and parsed into a Python dictionary before passing it to `set_token_set()`, or ensure `set_token_set` receives the JSON string directly (it expects a JSON string, not a dict).","cause":"The `token_set` passed to `api_client.set_token_set()` is not a valid JSON string, or it's not a dictionary when expected.","error":"json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0) or TypeError: 'int' object is not subscriptable"},{"fix":"Ensure you are following the correct OAuth2 Authorization Code Grant flow. Xero typically requires user consent for most API access, not just client credentials. Refer to the official Xero OAuth2 documentation.","cause":"You are attempting an OAuth2 grant type that is not supported by Xero (e.g., trying client_credentials for private apps, which Xero doesn't directly support for most API calls with the SDK).","error":"xero_python.exceptions.ApiException: (400) Reason: Bad Request - {'error': 'unsupported_grant_type', 'error_description': 'The authorization grant type is not supported by the authorization server.'}"}]}