Xero Python SDK

11.0.0 · active · verified Thu Apr 16

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.

Common errors

Warnings

Install

Imports

Quickstart

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.

import os
import json
from xero_python.accounting import AccountingApi
from xero_python.identity import IdentityApi
from xero_python.api_client import ApiClient, Configuration, ApiException

# IMPORTANT: In a real application, you would implement the full OAuth2 flow
# to obtain and refresh tokens securely. This example assumes you have
# a valid access token, refresh token, and tenant ID. 
# NEVER hardcode secrets or tokens in production code.

# Load your Xero API credentials from environment variables
CLIENT_ID = os.environ.get("XERO_CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.environ.get("XERO_CLIENT_SECRET", "YOUR_CLIENT_SECRET")
REFRESH_TOKEN = os.environ.get("XERO_REFRESH_TOKEN", "YOUR_REFRESH_TOKEN")
ACCESS_TOKEN = os.environ.get("XERO_ACCESS_TOKEN", "YOUR_ACCESS_TOKEN") # Often short-lived
TENANT_ID = os.environ.get("XERO_TENANT_ID", "YOUR_TENANT_ID") # Specific Xero organisation ID

# Initialize Xero API client configuration
config = Configuration()
# config.host can be set for specific regions if needed, e.g., 'https://api.xero.com' (default)

api_client = ApiClient(config)

# Set the OAuth2 configuration for token management (essential for refresh)
api_client.set_oauth2_config(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    tenant_id=TENANT_ID # This is the Xero Organisation ID you want to interact with
)

# Manually set an initial token set (for demonstration purposes)
# In a real app, you'd load this from secure storage and refresh as needed.
token_set = {
    "access_token": ACCESS_TOKEN,
    "refresh_token": REFRESH_TOKEN,
    "expires_at": 0 # Set to 0 to force immediate refresh if ACCESS_TOKEN is dummy/expired
}
api_client.set_token_set(json.dumps(token_set))

# --- Token Refresh (Crucial for long-lived applications) ---
# The SDK automatically tries to refresh if token_set.expires_at is in the past
# when making an API call. For explicit control, you might call:
try:
    api_client.refresh_token_set(token_set["refresh_token"])
    # After refresh, the token_set in api_client is updated.
    # You should persist this new token_set securely.
    # print("Token refreshed successfully.")
except ApiException as e:
    print(f"Error refreshing token: {e.body}")
    exit() # Cannot proceed without a valid token

# Initialize the Accounting API client
accounting_api = AccountingApi(api_client)

try:
    # Example: Get the first 5 contacts
    contacts = accounting_api.get_contacts(_page=1, _limit=5)

    if contacts.contacts:
        print("Successfully retrieved contacts:")
        for contact in contacts.contacts:
            print(f"- {contact.name} (ID: {contact.contact_id})")
    else:
        print("No contacts found.")

except ApiException as e:
    print(f"Xero API Error: Status {e.status}, Body: {e.body}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →