python-quickbooks

A Python library for accessing the Quickbooks API. Complete rework of quickbooks-python.

These instructions were written for a Django application. Make sure to change it to whatever framework/method you’re using. You can find additional examples of usage in Integration tests folder.

QuickBooks OAuth

As of July 17, 2017, all new applications connecting to QuickBook Online must use OAuth 2.0. Existing applications can continue to use OAuth 1.0 (See OAuth 1.0 vs. OAuth 2.0 for details)

Connecting your application with quickbooks-cli

From the command line, call quickbooks-cli tool passing in either your consumer_key and consumer_secret (OAuth 1.0) or your client_id and client_secret (OAuth 2.0), plus the OAuth version number:

quickbooks-cli [-h] [-s] [-p PORT] consumer_key consumer_secret oauth_version

Manually connecting with OAuth version 1.0

1. Create the Authorization URL for your application:

from quickbooks import Oauth1SessionManager

session_manager = Oauth1SessionManager(
    sandbox=True,
    consumer_key=QUICKBOOKS_CLIENT_KEY,
    consumer_secret=QUICKBOOKS_CLIENT_SECRET,
)

callback_url = 'http://localhost:8000'  # Quickbooks will send the response to this url
authorize_url = client.get_authorize_url(callback_url)
request_token = client.request_token
request_token_secret = client.request_token_secret

Store the authorize_url, request_token, and request_token_secret for use in the Callback method.

2. Handle the callback:

session_manager = Oauth1SessionManager(
    sandbox=True,
    consumer_key=QUICKBOOKS_CLIENT_KEY,
    consumer_secret=QUICKBOOKS_CLIENT_SECRET
)

session_manager.authorize_url = authorize_url
session_manager.request_token = request_token
session_manager.request_token_secret = request_token_secret

session_manager.get_access_tokens(request.GET['oauth_verifier'])

realm_id = request.GET['realmId']
access_token = session_manager.access_token
access_token_secret = session_manager.access_token_secret

Store realm_id, access_token, and access_token_secret for later use.

Manually connecting with OAuth version 2.0

1. Create the Authorization URL for your application:

from quickbooks import Oauth2SessionManager

session_manager = Oauth2SessionManager(
    sandbox=True,
    client_id=QUICKBOOKS_CLIENT_ID,
    client_secret=QUICKBOOKS_CLIENT_SECRET,
    base_url='http://localhost:8000',
)

callback_url = 'http://localhost:8000'  # Quickbooks will send the response to this url
authorize_url = client.get_authorize_url(callback_url)
request_token = client.request_token
request_token_secret = client.request_token_secret

Store the authorize_url, request_token, and request_token_secret for use in the Callback method.

2. Handle the callback:

session_manager = Oauth2SessionManager(
    sandbox=True,
    client_id=QUICKBOOKS_CLIENT_ID,
    client_secret=QUICKBOOKS_CLIENT_SECRET,
    base_url='http://localhost:8000',
)

session_manager.get_access_tokens(request.GET['code'])
access_token = client.access_token

Store access_token for later use.

Accessing the API

Set up an OAuth session manager to pass to the QuickBooks client. OAuth version 1.0 - Setup the session manager using the stored access_token and the access_token_secret and realm_id:

session_manager = Oauth1SessionManager(
    sandbox=True,
    consumer_key=CONSUMER_KEY,
    consumer_secret=CONSUMER_SECRET,
    access_token=ACCESS_TOKEN,
    access_token_secret=ACCESS_TOKEN_SECRET,
)

OAuth version 2.0 - Setup the session manager using the stored access_token and realm_id:

self.session_manager = Oauth2SessionManager(
    sandbox=True,
    client_id=realm_id,
    client_secret=CLIENT_SECRET,
    access_token=AUTH2_ACCESS_TOKEN,
)

Then create the QuickBooks client object passing in the session manager:

from quickbooks import QuickBooks

 client = QuickBooks(
     sandbox=True,
     session_manager=session_manager,
     company_id=realm_id
 )

If you need to access a minor version (See Minor versions for details) pass in minorversion when setting up the client:

client = QuickBooks(
    sandbox=True,
    consumer_key=QUICKBOOKS_CLIENT_KEY,
    consumer_secret=QUICKBOOKS_CLIENT_SECRET,
    access_token=access_token,
    access_token_secret=access_token_secret,
    company_id=realm_id,
    minorversion=4
)

You can disconnect the current Quickbooks Account like so (See Disconnect documentation for full details):

client.disconnect_account()

If your consumer_key never changes you can enable the client to stay running:

QuickBooks.enable_global()

You can disable the global client like so:

QuickBooks.disable_global()

List of objects:

from quickbooks.objects.customer import Customer
customers = Customer.all(qb=client)

Note: The maximum number of entities that can be returned in a response is 1000. If the result size is not specified, the default number is 100. (See Intuit developer guide for details)

Filtered list of objects:

customers = Customer.filter(Active=True, FamilyName="Smith", qb=client)

Filtered list of objects with paging:

customers = Customer.filter(start_position=1, max_results=25, Active=True, FamilyName="Smith", qb=client)

List Filtered by values in list:

customer_names = ['Customer1', 'Customer2', 'Customer3']
customers = Customer.choose(customer_names, field="DisplayName", qb=client)

List with custom Where Clause (do not include the "WHERE"):

customers = Customer.where("Active = True AND CompanyName LIKE 'S%'", qb=client)

List with custom Where Clause and paging:

customers = Customer.where("CompanyName LIKE 'S%'", start_position=1, max_results=25, qb=client)

Filtering a list with a custom query (See Intuit developer guide for supported SQL statements):

customers = Customer.query("SELECT * FROM Customer WHERE Active = True", qb=client)

Filtering a list with a custom query with paging:

customers = Customer.query("SELECT * FROM Customer WHERE Active = True STARTPOSITION 1 MAXRESULTS 25", qb=client)

Get single object by Id and update:

customer = Customer.get(1, qb=client)
customer.CompanyName = "New Test Company Name"
customer.save(qb=client)

Create new object:

customer = Customer()
customer.CompanyName = "Test Company"
customer.save(qb=client)

Batch Operations

The batch operation enables an application to perform multiple operations in a single request (See Intuit Batch Operations Guide for full details).

Batch create a list of objects:

from quickbooks.batch import batch_create

customer1 = Customer()
customer1.CompanyName = "Test Company 1"

customer2 = Customer()
customer2.CompanyName = "Test Company 2"

customers = []
customers.append(customer1)
customers.append(customer2)

results = batch_create(customers, qb=client)

Batch update a list of objects:

from quickbooks.batch import batch_update

customers = Customer.filter(Active=True)

# Update customer records

results = batch_update(customers, qb=client)

Batch delete a list of objects:

from quickbooks.batch import batch_delete

customers = Customer.filter(Active=False)
results = batch_delete(customers, qb=client)

Review results for batch operation:

# successes is a list of objects that were successfully updated
for obj in results.successes:
    print "Updated " + obj.DisplayName

# faults contains list of failed operations and associated errors
for fault in results.faults:
    print "Operation failed on " + fault.original_object.DisplayName

    for error in fault.Error:
        print "Error " + error.Message

Change Data Capture

Change Data Capture returns a list of objects that have changed since a given time (see Change data capture for more details):

from quickbooks.cdc import change_data_capture
from quickbooks.objects import Invoice

cdc_response = change_data_capture([Invoice], "2017-01-01T00:00:00", qb=client)
for invoice in cdc_response.Invoice:
    # Do something with the invoice

Querying muliple entity types at the same time:

from quickbooks.objects import Invoice, Customer

cdc_response = change_data_capture([Invoice, Customer], "2017-01-01T00:00:00", qb=client)

If you use a datetime object for the timestamp, it is automatically converted to a string:

from datetime import datetime

cdc_response = change_data_capture([Invoice, Customer], datetime(2017, 1, 1, 0, 0, 0), qb=client)

Attachments

See Attachable documentation for list of valid file types, file size limits and other restrictions.

Attaching a note to a customer:

attachment = Attachable()

attachable_ref = AttachableRef()
attachable_ref.EntityRef = customer.to_ref()

attachment.AttachableRef.append(attachable_ref)

attachment.Note = 'This is a note'
attachment.save(qb=client)

Attaching a file to customer:

attachment = Attachable()

attachable_ref = AttachableRef()
attachable_ref.EntityRef = customer.to_ref()

attachment.AttachableRef.append(attachable_ref)

attachment.FileName = 'Filename'
attachment._FilePath = '/folder/filename'  # full path to file
attachment.ContentType = 'application/pdf'
attachment.save(qb=client)

Working with JSON data

All objects include to_json and from_json methods.

Converting an object to JSON data:

account = Account.get(1, qb=client)
json_data = account.to_json()

Loading JSON data into a quickbooks object:

account = Account()
account.from_json(
  {
   "AccountType": "Accounts Receivable",
   "Name": "MyJobs"
  }
)
account.save(qb=client)

Date formatting

When setting date or datetime fields, Quickbooks requires a specific format. Formating helpers are available in helpers.py. Example usage:

date_string = qb_date_format(date(2016, 7, 22))
date_time_string = qb_datetime_format(datetime(2016, 7, 22, 10, 35, 00))
date_time_with_utc_string = qb_datetime_utc_offset_format(datetime(2016, 7, 22, 10, 35, 00), '-06:00')

Note: Objects and object property names match their Quickbooks counterparts and do not follow PEP8.

Note: This is a work-in-progress made public to help other developers access the QuickBooks API. Built for a Django project running on Python 2.