Mapping your objects to QuickBooks

Before writing sync code, decide how each object in your product maps to QuickBooks Desktop. The right mapping depends on how your customer keeps their books, so make the important choices configurable.

Common mappings

Your object	QuickBooks record	Notes
Customer, client, account	Customer (/customers)	Jobs are child customers (parentId), shown as Parent:Job in fullName
Supplier	Vendor (/vendors)
Product you stock	Inventory item	Quantity on hand is tracked by QuickBooks
Product you do not stock, or a fee	Non-inventory item or other charge item
Service or hourly work	Service item
Discount	Discount item	Percentage or fixed amount
Order not yet fulfilled	Sales order (not in Pro) or estimate
Invoice you bill later	Invoice	Paid later with a received payment
Sale paid immediately	Sales receipt	No receivable
Payment received against invoices	Receive payment	Apply to invoices with its application list
Refund	Credit memo, then a check or credit card refund
Bill from a supplier	Bill	Paid with a bill check payment or bill credit card payment
Expense paid immediately	Check or credit card charge
Bank transfer	Transfer
Adjustment	Journal entry	Debit and credit lines must balance

Ask your customer (or let them choose in your settings) which income account, item and class to use for your transactions. Many bookkeepers have strong preferences, and a wrong account means work for their accountant.

Matching existing records

Your customer’s file already has customers, items and accounts. Creating duplicates is the most common integration complaint. Match before you create:

1. Store the QuickBooks id once you know it. After the first match or create, map your record to the QuickBooks id and never match by name again.
2. Match on a stable key. For customers and vendors, name is unique across customers, vendors, employees and other names in QuickBooks. Look up candidates with fullNames or nameContains, then confirm with your customer when more than one could match.
3. Use externalId for records you create. Set it to your own record ID on create; then you can always find your records, even if someone renames them.
4. Let the customer review. A matching screen (“We found Acme Supply in QuickBooks. Link it?”) beats a silent heuristic.

QuickBooks names are case-insensitive and limited in length (41 characters for customers and vendors, 31 for items). Truncating or renaming your records to fit is your decision to make visibly; the API rejects values that are too long rather than cutting them.

Hierarchies

Customers, items, accounts and classes can be nested. name is the record’s own name; fullName joins every level with colons (Acme Supply:Warehouse job). A name only needs to be unique among its siblings, so two jobs named “Phase 1” under different customers are fine. Always store and compare id, not fullName.

Taxes

Sales tax in QuickBooks Desktop depends on the customer’s tax code and the tax item. When you create invoices or sales receipts, either set salesTaxCodeId and salesTaxItemId explicitly from your customer’s choices, or leave them out so QuickBooks applies the customer’s defaults. See Editions, versions and features.

Dates and numbers

Use your order date as transactionDate, your invoice number as refNumber when your customer wants matching numbers (QuickBooks allows 11 characters on invoices), and decimal strings for every amount. See Money, dates and data conventions.