Install & Compatibility
Where this runs
tested against v0.9.12 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.725s · 41.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.647s · 42MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QuickBooks
✓ from quickbooks import QuickBooks
✗ from quickbooks.client import QuickBooks
The QuickBooks class is directly available under the top-level package.
AuthClient
✓ from intuitlib.client import AuthClient
AuthClient is part of the `intuit-oauth` dependency, not directly from `python-quickbooks`.
Customer
✓ from quickbooks.objects.customer import Customer
Specific QuickBooks object models are imported from `quickbooks.objects`.
This quickstart demonstrates how to set up the `AuthClient` and `QuickBooks` client using environment variables for credentials. It then shows how to fetch a list of customers. Ensure you have registered your app with Intuit Developer and obtained `CLIENT_ID`, `CLIENT_SECRET`, `REFRESH_TOKEN`, `COMPANY_ID` (Realm ID), and configured a `REDIRECT_URI`.
import os
from intuitlib.client import AuthClient
from quickbooks import QuickBooks
from quickbooks.objects.customer import Customer
# Retrieve credentials from environment variables for security
CLIENT_ID = os.environ.get('QBO_CLIENT_ID', 'YOUR_CLIENT_ID')
CLIENT_SECRET = os.environ.get('QBO_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')
REFRESH_TOKEN = os.environ.get('QBO_REFRESH_TOKEN', 'YOUR_REFRESH_TOKEN')
COMPANY_ID = os.environ.get('QBO_COMPANY_ID', 'YOUR_COMPANY_ID') # Also known as Realm ID
REDIRECT_URI = os.environ.get('QBO_REDIRECT_URI', 'http://localhost:8000/callback')
ENVIRONMENT = os.environ.get('QBO_ENVIRONMENT', 'sandbox') # 'sandbox' or 'production'
# Initialize AuthClient
auth_client = AuthClient(
CLIENT_ID,
CLIENT_SECRET,
REDIRECT_URI,
ENVIRONMENT
)
# Initialize QuickBooks client
qb = QuickBooks(
auth_client=auth_client,
refresh_token=REFRESH_TOKEN,
company_id=COMPANY_ID,
minorversion=75 # Recommended: use the latest supported minor version
)
try:
# Automatically refresh token if needed (handled by the library)
# Fetch all customers
customers = Customer.all(qb=qb, max_results=10) # Limit results for demonstration
for customer in customers:
print(f"Customer ID: {customer.Id}, Display Name: {customer.DisplayName}")
# Example: Create a new customer (uncomment to run)
# new_customer = Customer()
# new_customer.DisplayName = "New Test Customer"
# new_customer.CompanyName = "Test Company, Inc."
# new_customer.save(qb=qb)
# print(f"Created new customer: {new_customer.DisplayName} (ID: {new_customer.Id})")
except Exception as e:
print(f"An error occurred: {e}")
# Implement robust error handling and token refresh logic in production
Debug
Known issues
breakingQuickBooks Online API minor versions 1-74 are being deprecated by Intuit starting August 1, 2025. If your application relies on specific behaviors or schemas from these older minor versions, it may break. The `python-quickbooks` library defaults the minor version to the minimum supported version (currently 75 in 0.9.12) which may change behavior for applications not explicitly setting a `minorversion` parameter.fixReview your application's use of minor versions. Ensure your `QuickBooks` client is initialized with a `minorversion` of 75 or higher (e.g., `minorversion=75`). Test thoroughly to ensure compatibility with the updated API schema. The library automatically sets the minor version to the latest supported, but explicit setting is good practice.
affects: 0.9.12 and earlier, affecting API calls made after August 1, 2025.
breakingPython 2 support has been completely removed from the library. Attempts to use it in a Python 2 environment will result in errors related to syntax, decorators, and removed dependencies.fixUpgrade your application to Python 3 (preferably 3.6+). Ensure all project dependencies are Python 3 compatible.
affects: 0.9.4+
deprecatedThe `simplejson` dependency was removed. If your application directly imported `simplejson` via an internal `python-quickbooks` path, those imports will now fail.fixReplace any direct references to `simplejson` with Python's standard `json` library, or ensure `simplejson` is installed as a top-level dependency if your application explicitly requires it for other reasons.
affects: 0.9.9+
gotchaOAuth 2.0 access tokens have a limited lifespan (typically 1 hour) and require a refresh token to obtain new access tokens. Failure to correctly manage and refresh tokens will lead to `401 Unauthorized` or `400 invalid_grant` errors.fixThe `python-quickbooks` library's `QuickBooks` client, when initialized with an `AuthClient` and `refresh_token`, is designed to automatically handle token refreshing. Ensure your application persists the latest `refresh_token` returned by `auth_client.refresh()` for future sessions, as refresh tokens can roll (change upon use).
affects: All versions
gotchaQueries for objects (e.g., `Customer.all()`) have a default maximum return of 100 entities and an absolute maximum of 1000 entities per single API call. Fetching large datasets requires pagination.fixFor larger datasets, use the `start_position` and `max_results` parameters with `all()` methods to paginate through results. Example: `Customer.all(qb=qb, start_position=1, max_results=1000)`.
affects: All versions
gotchaDirectly passing unsanitized user input into QuickBooks Query Language (QBL) can lead to security vulnerabilities (e.g., SQL injection-like attacks).fixAlways sanitize or validate any user-provided input before incorporating it into QBL queries to prevent malicious data from being executed against your QuickBooks data.
affects: All versions
Errors
Common errors & fixes
quickbooks.exceptions.AuthenticationException: Invalid OAuth2 token.
The QuickBooks API access token has expired, or the refresh token used to obtain a new one is invalid or has expired, often due to inactivity or incorrect OAuth flow management.
fixEnsure your AuthClient is correctly initialized with the latest refresh token and implement token persistence by saving updated access and refresh tokens after each successful refresh.
KeyError: 'SomeFieldName' (e.g., KeyError: 'DisplayName')
The specific key or field being accessed does not exist in the QuickBooks object (e.g., a customer, invoice line item) returned by the API, often because it's optional or not set for that particular entity.
fixUse the dictionary's `get()` method with a default value (e.g., `data.get('key', None)`) or check for key existence before attempting direct access. quickbooks.exceptions.QuickbooksException: 400 Bad Request: Validation Fault; ...
The data provided for an API operation (create, update) violates QuickBooks' business rules or validation constraints, resulting in a bad request error from the QuickBooks API.
fixReview the detailed error message in the exception to identify the specific validation issue and adjust the data payload to meet QuickBooks API requirements.
quickbooks.exceptions.QuickbooksException: Failed to acquire access token. Missing arguments.
The Quickbooks client or AuthClient was initialized without providing all necessary authentication credentials like consumer_key, consumer_secret, access_token, refresh_token, callback_url, or realm_id.
fixEnsure all required parameters are passed correctly to the Quickbooks constructor and that AuthClient is properly configured with your application's OAuth 2.0 credentials and tokens.
Upgrade
Version history
0.9.12latest on PyPI · released Apr 16, 2025
Audit
Dependencies
intuit-oauthrequiredRequired for OAuth 2.0 authentication with Intuit's APIs.