{"id":6442,"library":"python-quickbooks","title":"QuickBooks Online API Client","description":"python-quickbooks is an actively maintained Python 3 library designed for interacting with the QuickBooks Online API. It provides a convenient object-oriented interface to access and manage QuickBooks data, abstracting away the complexities of the REST API and OAuth 2.0 authentication. The library integrates with `intuit-oauth` for secure authentication. Releases appear on an as-needed basis, with multiple updates throughout the year.","status":"active","version":"0.9.12","language":"python","source_language":"en","source_url":"https://github.com/ej2/python-quickbooks","tags":["quickbooks","accounting","api-client","oauth","intuit"],"install":[{"cmd":"pip install python-quickbooks","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for OAuth 2.0 authentication with Intuit's APIs.","package":"intuit-oauth","optional":false}],"imports":[{"note":"The QuickBooks class is directly available under the top-level package.","wrong":"from quickbooks.client import QuickBooks","symbol":"QuickBooks","correct":"from quickbooks import QuickBooks"},{"note":"AuthClient is part of the `intuit-oauth` dependency, not directly from `python-quickbooks`.","symbol":"AuthClient","correct":"from intuitlib.client import AuthClient"},{"note":"Specific QuickBooks object models are imported from `quickbooks.objects`.","symbol":"Customer","correct":"from quickbooks.objects.customer import Customer"}],"quickstart":{"code":"import os\nfrom intuitlib.client import AuthClient\nfrom quickbooks import QuickBooks\nfrom quickbooks.objects.customer import Customer\n\n# Retrieve credentials from environment variables for security\nCLIENT_ID = os.environ.get('QBO_CLIENT_ID', 'YOUR_CLIENT_ID')\nCLIENT_SECRET = os.environ.get('QBO_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')\nREFRESH_TOKEN = os.environ.get('QBO_REFRESH_TOKEN', 'YOUR_REFRESH_TOKEN')\nCOMPANY_ID = os.environ.get('QBO_COMPANY_ID', 'YOUR_COMPANY_ID') # Also known as Realm ID\nREDIRECT_URI = os.environ.get('QBO_REDIRECT_URI', 'http://localhost:8000/callback')\nENVIRONMENT = os.environ.get('QBO_ENVIRONMENT', 'sandbox') # 'sandbox' or 'production'\n\n# Initialize AuthClient\nauth_client = AuthClient(\n    CLIENT_ID,\n    CLIENT_SECRET,\n    REDIRECT_URI,\n    ENVIRONMENT\n)\n\n# Initialize QuickBooks client\nqb = QuickBooks(\n    auth_client=auth_client,\n    refresh_token=REFRESH_TOKEN,\n    company_id=COMPANY_ID,\n    minorversion=75 # Recommended: use the latest supported minor version\n)\n\ntry:\n    # Automatically refresh token if needed (handled by the library)\n    # Fetch all customers\n    customers = Customer.all(qb=qb, max_results=10) # Limit results for demonstration\n    for customer in customers:\n        print(f\"Customer ID: {customer.Id}, Display Name: {customer.DisplayName}\")\n\n    # Example: Create a new customer (uncomment to run)\n    # new_customer = Customer()\n    # new_customer.DisplayName = \"New Test Customer\"\n    # new_customer.CompanyName = \"Test Company, Inc.\"\n    # new_customer.save(qb=qb)\n    # print(f\"Created new customer: {new_customer.DisplayName} (ID: {new_customer.Id})\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    # Implement robust error handling and token refresh logic in production\n","lang":"python","description":"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`."},"warnings":[{"fix":"Review 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.","message":"QuickBooks 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.","severity":"breaking","affected_versions":"0.9.12 and earlier, affecting API calls made after August 1, 2025."},{"fix":"Upgrade your application to Python 3 (preferably 3.6+). Ensure all project dependencies are Python 3 compatible.","message":"Python 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.","severity":"breaking","affected_versions":"0.9.4+"},{"fix":"Replace 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.","message":"The `simplejson` dependency was removed. If your application directly imported `simplejson` via an internal `python-quickbooks` path, those imports will now fail.","severity":"deprecated","affected_versions":"0.9.9+"},{"fix":"The `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).","message":"OAuth 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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)`.","message":"Queries 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always sanitize or validate any user-provided input before incorporating it into QBL queries to prevent malicious data from being executed against your QuickBooks data.","message":"Directly passing unsanitized user input into QuickBooks Query Language (QBL) can lead to security vulnerabilities (e.g., SQL injection-like attacks).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.0':47 '3':13 'abstract':37 'access':32 'account':74 'activ':10 'api':3,22,44,76 'api-cli':75 'appear':60 'as-need':63 'authent':48,58 'away':38 'basi':66 'client':4,77 'complex':40 'conveni':26 'data':36 'design':15 'integr':51 'interact':17 'interfac':30 'intuit':54,79 'intuit-oauth':53 'librari':14,50 'maintain':11 'manag':34 'multipl':68 'need':65 'oauth':46,55,78 'object':28 'object-ori':27 'onlin':2,21 'orient':29 'provid':24 'python':6,12 'python-quickbook':5 'quickbook':1,7,20,35,73 'releas':59 'rest':43 'secur':57 'throughout':70 'updat':69 'year':72","created_at":"2026-04-15T05:37:29.721055+00:00","updated_at":"2026-04-16T20:27:24.122789+00:00","problems":[{"fix":"Ensure 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.","cause":"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.","error":"quickbooks.exceptions.AuthenticationException: Invalid OAuth2 token."},{"fix":"Use the dictionary's `get()` method with a default value (e.g., `data.get('key', None)`) or check for key existence before attempting direct access.","cause":"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.","error":"KeyError: 'SomeFieldName' (e.g., KeyError: 'DisplayName')"},{"fix":"Review the detailed error message in the exception to identify the specific validation issue and adjust the data payload to meet QuickBooks API requirements.","cause":"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.","error":"quickbooks.exceptions.QuickbooksException: 400 Bad Request: Validation Fault; ..."},{"fix":"Ensure 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.","cause":"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.","error":"quickbooks.exceptions.QuickbooksException: Failed to acquire access token. Missing arguments."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.12","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ej2/python-quickbooks","docs":null,"changelog":null,"pypi":"https://pypi.org/project/python-quickbooks/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["crm-productivity","auth-security","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}