QuickBooks

Procedures and concepts for the QuickBooks integration.

The following documentation is for QuickBooks v2.6.0 (BDK).

Overview

QuickBooks is a leading accounting software solution for small to medium-sized businesses. This integration enables automated financial data entry, invoice processing, expense tracking, and reporting workflows. Streamline accounting processes and maintain accurate financial records through automation.

Prerequisites

1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

• QuickBooks

How to Add the Book(s)

1. Go to Books → All Books.

2. Search for the name of the book and click on it.

3. Click on Install or Add Connection to add the book to your agent.

4. If adding a connection, you'll be prompted for connectivity details.

Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

This books supports the connectivity methods described in this section.In here you will find information about what information is required in order to employ each method.

Connect using token

Connects to QuickBooks using OAuth access token.

Label	Description	Type
token	The OAuth access token for QuickBooks authentication.	text

Configuration

The following table details all the available configuration options for this book.

Concept	Description	Type	Default Value
company id	Get the value of the company id.	number	(no default)
quickbook environment	Get the current environment.	enum[production, sandbox]	(no default)

Configuration can be set or retrieved as shown in the following examples:

Procedures

to attach a file to the (bill) and get the attachment

Upload an attachment to an existing bill in QuickBooks.

Input Concepts

Concept	Description	Type	Required	Default Value
bill	The Bill concept object to attach the file to.	quickbooks bill	Yes	(no default)
file	The file-like object to upload.	file	Yes	(no default)
file name	The name of the file to be attached.	text	Yes	(no default)
note	Optional note to add to the attachment.	text	No	(no default)

Output Concepts

Concept	Description	Type
attachment	The Attachment concept object with updated attachment information.	quickbooks attachment

Examples

the bill
the file
attach the file to the bill
  the file name is "attachment.pdf"
  the note is "This is an attachment note"

to create a bill

Create a new bill in QuickBooks from the provided bill details.

Input Concepts

Concept	Description	Type	Required	Default Value
bill	A BillInput object containing all bill details.	quickbooks bill input	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	The newly created bill.	quickbooks bill

Examples

Create a bill with mixed line items.

set the department's company id to 9341455406391846
the vendor
get '{"items":[{"name":"Sprinkler Heads","amount":200.00,"quantity":4,"unit_price":50.00},{"account_name":"Supplies","amount":75.00,"description":"Miscellaneous office expenses"}]}' as a json
use the above as bill
set the bill's vendor to the vendor
create the bill

Create a bill with all optional fields for item-based line items.

set the department's company id to 9341455406391846
the vendor
the customer
get the customer as a string
get '{"terms":"Net 30","bill_date":"2025-07-15","due_date":"2025-08-14","bill_no":"COMPLETE-123","items":[{"name":"Sprinkler Heads","amount":200.00,"description":"Premium sprinkler heads","customer": {the customer},"quantity":4,"unit_price":50.00,"billable_status":"Billable"}]}' as a json
use the above as bill
set the bill's vendor to the vendor
create the bill

Create a bill with account-based line items.

set the department's company id to 9341455406391846
the vendor
the customer
get the customer as a string
get '{"items":[{"account_name":"Supplies","amount":150.00,"description":"Office supplies expense","customer": {the customer}}]}' as a json
set the bill's vendor to the vendor
use the above as bill
create the bill

to create a bill from a (purchase order)

Create a new bill in QuickBooks based on an existing purchase order.

Input Concepts

Concept	Description	Type	Required	Default Value
purchase order	The purchase order to convert into a bill.	quickbooks purchase order	Yes	(no default)

Output Concepts

Concept	Description	Type
purchase order	The newly created bill.	quickbooks bill

Examples

Create a bill for a specific purchase order by doc number.

retrieve the purchase orders whose doc_number is "PO-12345"
use the first purchase order as the purchase order
create the bill from the purchase order

to create an invoice

Create a new invoice in QuickBooks from the provided invoice details.

Input Concepts

Concept	Description	Type	Required	Default Value
invoice	An InvoiceInput object containing all invoice details.	quickbooks invoice input	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	The newly created invoice.	quickbooks invoice

Examples

Create an invoice with sales item line.

set the department's company id to 9341455406391846
the customer
get '{"items":[{"name":"Sprinkler Heads","amount":200.00,"quantity":4,"unit_price":50.00}]}' as a json
use the above as invoice
set the invoice's customer to the customer
create the invoice

Create an invoice with all optional fields.

set the department's company id to 9341455406391846
the customer
get '{"terms":"Net 30","invoice_date":"2025-07-15","due_date":"2025-08-14","invoice_no":"INV-001","items":[{"name":"Sprinkler Heads","amount":200.00,"description":"Premium sprinkler heads","quantity":4,"unit_price":50.00}]}' as a json
use the above as invoice
set the invoice's customer to the customer
create the invoice

Create an invoice with description-only lines.

set the department's company id to 9341455406391846
the customer
get '{"items":[{"description":"This is a note line"},{"name":"Sprinkler Heads","amount":100.00}]}' as a json
use the above as invoice
set the invoice's customer to the customer
create the invoice

to delete an (invoice)

Delete/void an invoice in QuickBooks.

QuickBooks marks invoices as inactive rather than hard deleting them.

Input Concepts

Concept	Description	Type	Required	Default Value
invoice	The Invoice concept object to delete.	quickbooks invoice	Yes	(no default)

Output Concepts

Concept	Description	Type
invoice	None	thing

Examples

retrieve the invoices whose doc_number is "INV-001"
use the first invoice as the invoice
delete the invoice

to delete an invoice by id

Delete/void an invoice in QuickBooks by invoice ID.

QuickBooks marks invoices as inactive rather than hard deleting them.

Input Concepts

Concept	Description	Type	Required	Default Value
invoice id	The invoice ID to delete.	text	Yes	(no default)

Examples

delete the invoice by id
    the invoice id is 12345

to edit a bill

Edit an existing bill in QuickBooks by updating it with new information.

Input Concepts

Concept	Description	Type	Required	Default Value
bill	The Bill concept object containing the updated bill information.	quickbooks bill	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	The updated bill from QuickBooks.	quickbooks bill

Examples

the bill
the customer
the bill's "items"
use the above as the lines
get the first line as the item
set the item's "billable_status" to "BILLABLE"
set the item's customer to the customer
set the bill's "items" to the items
edit the bill

to edit an (invoice)

Edit an existing invoice in QuickBooks by updating it with new information.

Input Concepts

Concept	Description	Type	Required	Default Value
invoice	The Invoice concept object containing the updated invoice information.	quickbooks invoice	Yes	(no default)

Output Concepts

Concept	Description	Type
invoice	The updated invoice from QuickBooks.	quickbooks invoice

Examples

retrieve the invoices whose doc_number is "INV-001"
use the first invoice as the invoice
set the invoice's due_date to "2025-02-15"
set the invoice's invoice_date to "2025-01-15"
edit the invoice

to retrieve (bills)

FILTER - CAPABLE

Retrieve bills in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of bills to retrieve.	number	No	(no default)
offset	The number which starts the bills to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
bills	The bills associated with the company.	quickbooks bill

Examples

retrieve the bills whose doc_number is "BILL-12345"

to retrieve (customers)

FILTER - CAPABLE

Retrieve customers in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of customers to retrieve.	number	No	(no default)
offset	The number which starts the customers to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
customers	The customers associated with the company.	quickbooks customer

Examples

retrieve the customers whose display_name has "Cool"
use the first customer as the customer

to retrieve (invoices)

FILTER - CAPABLE

Retrieve invoices in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of invoices to retrieve.	number	No	(no default)
offset	The number which starts the invoices to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
invoices	The invoices associated with the company.	quickbooks invoice

Examples

retrieve the invoices whose doc_number is "INV-12345"

to retrieve (items)

FILTER - CAPABLE

Retrieve items in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of items to retrieve.	number	No	(no default)
offset	The number which starts the items to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
items	The items associated with the company.	quickbooks item

Examples

retrieve the items whose name is "Sprinkler Heads"
retrieve the items whose type is "Category"
retrieve the items whose is_active is True

to retrieve (purchase orders)

FILTER - CAPABLE

Retrieve purchase orders in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of purchase orders to retrieve.	number	No	(no default)
offset	The number which starts the purchase orders to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
purchase orders	The purchase orders associated with the company.	quickbooks purchase order

Examples

retrieve the purchase orders whose vendor_name is "ABC Company"
retrieve the purchase orders whose doc_number is "1004"
retrieve the purchase orders whose vendor_name has "ABC" and po_number is "PO-12345"

to retrieve (vendors)

FILTER - CAPABLE

Retrieve vendors in QuickBooks from the company.

Input Concepts

Concept	Description	Type	Required	Default Value
limit	The maximum number of messages to retrieve.	number	No	(no default)
offset	The number which starts the messages to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
vendors	The vendors associated with the company.	quickbooks vendor

Examples

retrieve the vendors whose display_name is "Pam Seitz"
use the first vendor as the vendor

to retrieve a (report)

Retrieve a specific report from QuickBooks.

This procedure handles both summary and detail AR/AP reports.

Input Concepts

Concept	Description	Type	Required	Default Value
report type	The type of report to retrieve (AR summary, AR detail, AP summary, AP detail, account list detail, or transaction list).	enum[account_list_detail, ap_detail, ap_summary, ar_detail, ar_summary, transaction_list]	Yes	(no default)
date macro	Predefined date range (e.g., "All", "This Month", "Last Quarter"). Mutually exclusive with start_date/end_date.	text	No	(no default)
start date	Start date for custom range in YYYY-MM-DD format. Must be used with end_date.	text	No	(no default)
end date	End date for custom range in YYYY-MM-DD format. Must be used with start_date.	text	No	(no default)

Output Concepts

Concept	Description	Type
report	A Report object containing the report header, columns, and grouped table sections.	quickbooks report

Examples

retrieve the report from quickbooks
    the report type is "AP_DETAIL"
    the date macro is "All"
retrieve the report from quickbooks
    the report type is "ACCOUNT_LIST_DETAIL"
    the date macro is "This Month"
retrieve the report from quickbooks
    the report type is "TRANSACTION_LIST"
    the start date is "2024-01-01"
    the end date is "2024-12-31"

to update an (item)

Update an existing item in QuickBooks.

Input Concepts

Concept	Description	Type	Required	Default Value
item	The Item concept object containing the updated item information.	quickbooks item	Yes	(no default)

Output Concepts

Concept	Description	Type
item	The updated item from QuickBooks.	quickbooks item

Examples

retrieve the items whose name is "Sprinkler Heads"
use the first item as the item
set the item's unit_price to 75.00
set the item's description to "Updated description"
update the item

Concepts

Quickbooks bill input

Input data for creating a QuickBooks Bill with mixed line item types.

Field Name	Description	Type
vendor	The vendor in QuickBooks.	json
items	List of line items (can be item-based or account-based).	list of list of any
terms	Optional sales terms name.	optional[text]
bill_date	The bill date in YYYY-MM-DD format.	optional[text]
due_date	The due date in YYYY-MM-DD format.	optional[text]
bill_no	Optional bill number.	optional[text]

Quickbooks vendor

A comprehensive representation of a QuickBooks Vendor.

Field Name	Description	Type
id	The unique identifier for the vendor.	text
display_name	The display name of the vendor.	text
company_name	The company name of the vendor.	optional[text]
first_name	The first name of the vendor contact person.	optional[text]
last_name	The last name of the vendor contact person.	optional[text]
print_on_check_name	The name to print on checks.	optional[text]
email	The primary email address of the vendor.	optional[text]
phone	The primary phone number of the vendor.	optional[text]
website	The vendor's website URL.	optional[text]
billing_address	The billing address of the vendor.	optional[quickbooks address]
account_number	The vendor's account number.	optional[text]
balance	The current balance owed to the vendor.	optional[number]
default_terms	The default payment terms for the vendor.	optional[text]
is_1099_contractor	Whether the vendor is a 1099 contractor.	optional[boolean]
is_active	Whether the vendor is currently active.	optional[boolean]

Quickbooks bill

A created QuickBooks Bill.

Field Name	Description	Type
id	The unique identifier of the bill in QuickBooks.	text
doc_number	The document number of the bill.	text
vendor_name	The name of the vendor.	text
total_amount	The total amount of the bill.	number
balance	The current balance of the bill from QuickBooks.	number
bill_date	The bill date.	optional[text]
due_date	The due date.	optional[text]
terms	The payment terms reference with id and name.	optional[json]
location	The department/location reference with id and name.	optional[json]
items	List of bill line items.	optional[list of list of quickbooks item or quickbooks account based line?]
custom_fields	List of custom fields associated with the bill.	optional[list of quickbooks custom field]
attachment_ref	The attachment reference if an attachment was uploaded.	optional[quickbooks attachment]
created_time	When the bill was created.	optional[text]
last_updated	When the bill was last updated	optional[text]

Quickbooks custom field

Represents a custom field in QuickBooks.

Field Name	Description	Type
definition_id	The unique identifier for the custom field definition.	text
name	The name of the custom field.	text
field_type	The type of the custom field (e.g., 'StringType').	text
string_value	The string value of the custom field.	optional[text]

Quickbooks attachment

An attachment to a QuickBooks bill.

Field Name	Description	Type
id	The unique identifier of the attachment in QuickBooks.	text
file_name	The name of the attached file.	text
note	Optional note associated with the attachment.	optional[text]
content_type	The MIME type of the attachment.	optional[text]
size	The size of the attachment in bytes.	optional[number]

Quickbooks purchase order

A created QuickBooks Purchase Order.

Field Name	Description	Type
id	The unique identifier of the purchase order in QuickBooks.	text
doc_number	The document number of the purchase order.	text
vendor_name	The name of the vendor.	text
total_amount	The total amount of the purchase order.	number
po_status	The status of the purchase order (e.g., "Open", "Closed").	optional[text]
po_date	The purchase order date.	optional[text]
due_date	The due date.	optional[text]
memo	Memo or notes for the purchase order.	optional[text]
private_note	Private note for the purchase order.	optional[text]
terms	The payment terms reference.	optional[json]
location	The department/location.	optional[json]
ship_method	The shipping method.	optional[text]
vendor_address	The vendor address for the purchase order.	optional[text]
ship_address	The shipping address.	optional[text]
exchange_rate	The exchange rate used.	optional[number]
global_tax_calculation	The tax calculation method.	optional[text]
items	List of purchase order line items.	optional[list of list of any?]
custom_fields	List of custom fields associated with the purchase order.	optional[list of quickbooks custom field]
created_time	When the purchase order was created.	optional[text]
last_updated	When the purchase order was last updated.	optional[text]

Quickbooks invoice input

Input data for creating a QuickBooks Invoice with mixed line item types.

Field Name	Description	Type
customer	The customer in QuickBooks.	json
items	List of line items (can be sales-item or description-only).	list of list of any
custom_fields	Optional list of custom fields for the invoice.	optional[list of quickbooks custom field]
terms	Optional sales terms name.	optional[text]
invoice_date	The invoice date in YYYY-MM-DD format.	optional[text]
due_date	The due date in YYYY-MM-DD format.	optional[text]
invoice_no	Optional invoice number.	optional[text]

Quickbooks customer

A comprehensive representation of a QuickBooks Customer.

Field Name	Description	Type
id	The unique identifier for the customer.	text
display_name	The display name of the customer.	text
company_name	The company name of the customer.	optional[text]
first_name	The first name of the customer contact person.	optional[text]
last_name	The last name of the customer contact person.	optional[text]
print_on_check_name	The name to print on checks.	optional[text]
email	The primary email address of the customer.	optional[text]
phone	The primary phone number of the customer.	optional[text]
website	The customer's website URL.	optional[text]
billing_address	The billing address of the customer.	optional[quickbooks address]
shipping_address	The shipping address of the customer.	optional[quickbooks address]
account_number	The customer's account number.	optional[text]
balance	The current balance owed by the customer.	optional[number]
default_terms	The default payment terms for the customer.	optional[text]
is_active	Whether the customer is currently active.	optional[boolean]

Quickbooks invoice

A created QuickBooks Invoice.

Field Name	Description	Type
id	The unique identifier of the invoice in QuickBooks.	text
doc_number	The document number of the invoice.	text
customer_name	The name of the customer.	text
total_amount	The total amount of the invoice.	number
balance	The current balance of the invoice from QuickBooks.	number
invoice_date	The invoice date.	optional[text]
due_date	The due date.	optional[text]
terms	The sales terms name.	optional[text]
items	List of invoice line items.	optional[list of list of quickbooks sales item line or quickbooks description only line?]
custom_fields	List of custom fields associated with the invoice.	optional[list of quickbooks custom field]
created_time	When the invoice was created.	optional[text]
last_updated	When the invoice was last updated	optional[text]

Thing

No description

Quickbooks item

A QuickBooks item (product, service, or category).

Field Name	Description	Type
id	The unique identifier for the item	text
name	The name of the item	text
type	The type of item (Service, Inventory, NonInventory, Category, etc.)	text
sku	The SKU code for the item	optional[text]
description	Description of the item	optional[text]
unit_price	The unit price for sales	optional[number]
purchase_cost	The cost to purchase the item	optional[number]
qty_on_hand	Quantity on hand (for inventory items)	optional[number]
income_account_ref	Reference to the income account	optional[json]
expense_account_ref	Reference to the expense account	optional[json]
asset_account_ref	Reference to the asset account	optional[json]
parent_ref	Reference to the parent category (for sub-categories)	optional[json]
is_active	Whether the item is active	optional[boolean]
sync_token	The sync token for updates	optional[text]
created_time	The timestamp when the item was created	optional[text]
last_updated	The timestamp when the item was last updated	optional[text]
taxable	Whether the item is taxable	optional[boolean]
fully_qualified_name	The fully qualified name of the item	optional[text]
purchase_desc	Purchase description of the item	optional[text]
track_qty_on_hand	Whether to track quantity on hand	optional[boolean]
inv_start_date	The inventory start date (for inventory items)	optional[text]
domain	The domain of the item	optional[text]
sparse	Whether the item is sparse	optional[boolean]

Quickbooks report

A QuickBooks report with its header, columns, and grouped table sections.This concept represents quickbooks reports, where data is organized into logical groupings.

Field Name	Description	Type
report_type	The type of report that was generated	enum[account_list_detail, ap_detail, ap_summary, ar_detail, ar_summary, transaction_list]
header	Header information containing report metadata	json
columns	Column definitions for the report	list of json
tables	List of table sections, each representing a grouped data section	list of json

Concept attribute specifications

terms (quickbooks bill)

Name	Type
id	optional[text]
name	optional[text]

location (quickbooks bill)

Name	Type
id	optional[text]
name	optional[text]

terms (quickbooks purchase order)

Name	Type
id	optional[text]
name	optional[text]

location (quickbooks purchase order)

Name	Type
id	optional[text]
name	optional[text]

income_account_ref (quickbooks item)

Name	Type
id	optional[text]
name	optional[text]

expense_account_ref (quickbooks item)

Name	Type
id	optional[text]
name	optional[text]

asset_account_ref (quickbooks item)

Name	Type
id	optional[text]
name	optional[text]

parent_ref (quickbooks item)

Name	Type
id	optional[text]
name	optional[text]

columns (quickbooks report)

Name	Type
col_type	text
col_title	text
metadata	optional[json]

tables (quickbooks report)

Name	Type
header	text
data	table
type	text
group	optional[text]
raw_data	optional[json]