QuickBooks Online API Client

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your application to Python 3 (preferably 3.6+). Ensure all project dependencies are Python 3 compatible.
• deprecated The `simplejson` dependency was removed. If your application directly imported `simplejson` via an internal `python-quickbooks` path, those imports will now fail.
  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.
• gotcha 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.
  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).
• gotcha 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.
  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)`.
• gotcha Directly passing unsanitized user input into QuickBooks Query Language (QBL) can lead to security vulnerabilities (e.g., SQL injection-like attacks).
  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.

Install

• pip install python-quickbooks Install stable version

Imports

• QuickBooks

  from quickbooks 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`.

Quickstart

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