node-quickbooks is a Node.js client library for working with Intuit's QuickBooks API. It provides callback-based methods for common QuickBooks Online operations, including creating, reading, updating, deleting, querying, reporting, batch requests, change data capture, PDF retrieval/emailing, and file uploads as attachables.
The library supports OAuth 2.0 usage by passing false for the token secret and providing an OAuth 2.0 refresh token.
npm install node-quickbooksvar QuickBooks = require('node-quickbooks')
var qbo = new QuickBooks(
consumerKey,
consumerSecret,
oauthToken,
false,
realmId,
false,
true,
null,
'2.0',
refreshToken
)
qbo.getBillPayment('42', function(err, billPayment) {
if (err) console.log(err)
else console.log(billPayment)
})QuickBooks(
consumerKey,
consumerSecret,
oauth_token,
oauth_token_secret,
realmId,
useSandbox,
debug,
minorVer,
oAuthVer,
refresh_token
)consumerKey- The application's consumer key.consumerSecret- The application's consumer secret.oauth_token- The user's generated token.oauth_token_secret- The user's generated secret. Usefalsefor OAuth 2.0.realmId- The QuickBooks company ID.useSandbox- Boolean flag for QuickBooks sandbox usage.debug- Boolean flag to log HTTP requests, headers, and response bodies.minorVer- QuickBooks API minor version, ornullto avoid specifying one.oAuthVer- Use'2.0'for OAuth 2.0.refresh_token- The user's generated refresh token.
The client includes create methods for QuickBooks entities such as:
createAccountcreateAttachablecreateBillcreateBillPaymentcreateClasscreateCreditMemocreateCustomercreateDepartmentcreateDepositcreateEmployeecreateEstimatecreateInvoicecreateItemcreateJournalEntrycreatePaymentcreatePurchasecreatePurchaseOrdercreateRefundReceiptcreateSalesReceiptcreateTaxAgencycreateTermcreateTimeActivitycreateTransfercreateVendorcreateVendorCredit
Example:
qbo.createAttachable({ Note: 'My File' }, function(err, attachable) {
if (err) console.log(err)
else console.log(attachable.Id)
})Read methods retrieve QuickBooks entities by ID or, where applicable, by options:
getAccountgetAttachablegetBillgetBillPaymentgetCompanyInfogetCreditMemogetCustomergetDepartmentgetDepositgetEmployeegetEstimategetExchangeRategetInvoicegetItemgetJournalEntrygetPaymentgetPreferencesgetPurchasegetPurchaseOrdergetRefundReceiptgetSalesReceiptgetTaxAgencygetTaxCodegetTaxRategetTermgetTimeActivitygetVendorgetVendorCredit
Example:
qbo.getBillPayment('42', function(err, billPayment) {
console.log(billPayment)
})Update methods persist changes to existing QuickBooks entities. Updated objects generally need Id and SyncToken fields.
qbo.updateCustomer({
Id: '42',
SyncToken: '1',
sparse: true,
PrimaryEmailAddr: {
Address: 'customer@example.com'
}
}, function(err, customer) {
if (err) console.log(err)
else console.log(customer)
})Supported update methods include:
updateAccountupdateAttachableupdateBillupdateBillPaymentupdateCompanyInfoupdateCreditMemoupdateCustomerupdateDepartmentupdateDepositupdateEmployeeupdateEstimateupdateInvoiceupdateItemupdateJournalEntryupdatePaymentupdatePreferencesupdatePurchaseupdatePurchaseOrderupdateRefundReceiptupdateSalesReceiptupdateTaxAgencyupdateTaxCodeupdateTaxRateupdateTermupdateTimeActivityupdateTransferupdateVendorupdateVendorCreditupdateExchangeRate
Delete methods accept either an entity or an ID. If an ID is passed, the library retrieves the entity first.
Supported delete methods include:
deleteAttachabledeleteBilldeleteBillPaymentdeleteCreditMemodeleteDepositdeleteEstimatedeleteInvoicedeleteJournalEntrydeletePaymentdeletePurchasedeletePurchaseOrderdeleteRefundReceiptdeleteSalesReceiptdeleteTimeActivitydeleteTransferdeleteVendorCredit
Example:
qbo.deleteAttachable('42', function(err, attachable) {
if (err) console.log(err)
else console.log(attachable)
})Query methods accept optional criteria. Criteria can be supplied as an object or as an array of objects with field, value, and optional operator keys.
qbo.findAttachables({
Note: 'My sample note field'
}, function(err, attachables) {
console.log(attachables)
})Array-style criteria can express operators such as =, IN, <, >, <=, >=, and LIKE.
qbo.findTimeActivities([
{ field: 'TxnDate', value: '2014-12-01', operator: '>' },
{ field: 'TxnDate', value: '2014-12-03', operator: '<' },
{ field: 'limit', value: 5 }
], function(err, timeActivities) {
console.log(timeActivities)
})Use asc or desc in the criteria object.
qbo.findAttachables({
desc: 'MetaData.LastUpdatedTime'
}, function(err, attachables) {
console.log(attachables)
})Use limit and offset.
qbo.findAttachables({
limit: 10,
offset: 10
}, function(err, attachables) {
console.log(attachables)
})The default and maximum limit is 1000 records per request. Passing fetchAll: true issues additional requests as needed to retrieve all available records.
qbo.findCustomers({
fetchAll: true
}, function(err, customers) {
console.log(customers)
})Use count: true to request row counts instead of full result sets.
qbo.findAttachables({
count: true
}, function(err, attachables) {
console.log(attachables)
})The client includes methods for QuickBooks report endpoints, including:
reportBalanceSheetreportProfitAndLossreportProfitAndLossDetailreportTrialBalancereportCashFlowreportInventoryValuationSummaryreportCustomerSalesreportItemSalesreportCustomerIncomereportCustomerBalancereportCustomerBalanceDetailreportAgedReceivablesreportAgedReceivableDetailreportVendorBalancereportVendorBalanceDetailreportAgedPayablesreportAgedPayableDetailreportVendorExpensesreportTransactionListreportGeneralLedgerDetailreportDepartmentSalesreportClassSales
Example:
qbo.reportBalanceSheet({ department: '1,4,7' }, function(err, balanceSheet) {
console.log(balanceSheet)
})Files can be uploaded as QuickBooks attachables, optionally linked to a QuickBooks entity.
qbo.upload(
'contractor.jpg',
'image/jpeg',
fs.createReadStream('contractor.jpg'),
'Invoice',
40,
function(err, data) {
console.log(err)
console.log(data)
}
)The upload method accepts:
filename- File name.contentType- MIME type.stream- Readable stream of file contents.entityType- Optional QuickBooks entity type, such asInvoice.entityId- Optional QuickBooks entity ID.callback- Callback receiving the created attachable.
The client includes PDF retrieval and email methods for supported QuickBooks documents:
getInvoicePdfgetCreditMemoPdfgetSalesReceiptPdfsendInvoicePdfsendCreditMemoPdfsendEstimatePdfsendSalesReceiptPdfsendPurchaseOrder
Email methods can use the email address stored on the QuickBooks document or an optional sendTo address.
batch(items, callback) performs multiple supported operations in one request.
Supported batch item types:
createupdatedeletequery
The maximum number of batch items in a single request is 30.
changeDataCapture(entities, since, callback) returns entities changed since a specified time.
entitiesmay be a comma-separated list or JavaScript array.sincemay be a JavaScriptDateor a string such as2012-07-20T22:25:51-07:00.
The example directory contains a barebones Express application demonstrating the OAuth workflow.
The example workflow includes:
- creating an Intuit Developer application,
- configuring the OAuth consumer key and secret,
- starting the example app,
- visiting
http://localhost:3000/start, - completing the Intuit OAuth authorization flow,
- receiving OAuth values through the callback flow.
The original setup notes state that OAuth credentials must be obtained from the Intuit Developer portal and configured in the example application before use.
Tests require QuickBooks API credentials in config.js.
The original README notes that the following values are needed:
consumerKeyconsumerSecrettokentokenSecretrealmId
After credentials are configured, tests can be run with:
npm testnode-quickbooks is intended for Node.js applications that need to interact with QuickBooks Online data through Intuit's API. Typical usage includes:
- creating and updating customers, invoices, bills, vendors, and other accounting entities,
- querying QuickBooks records with filters, sorting, pagination, and counts,
- retrieving financial reports such as balance sheets and profit-and-loss reports,
- uploading attachable files and linking them to QuickBooks entities,
- sending or retrieving PDFs for invoices, credit memos, estimates, sales receipts, and purchase orders,
- using batch operations for grouped API work,
- using change data capture to identify entities changed after a given time.
Yes. The documented constructor example uses OAuth 2.0 by passing false for the token secret, setting the OAuth version to '2.0', and passing a refresh token.
Yes. Query methods can use criteria objects for filters, sorting, limits, offsets, counts, and fetchAll.
Yes. The documented API includes report methods such as balance sheet, profit and loss, trial balance, cash flow, customer reports, vendor reports, and transaction reports.
Yes. The upload method uploads a file as an attachable and can optionally link it to a QuickBooks entity.
Yes. Batch operations support create, update, delete, and query items, with a documented maximum of 30 batch items per request.
The original README documents npm test, but tests require QuickBooks API credentials configured in config.js.