# Mapping your objects to QuickBooks
Source: https://www.desktopaccountingapi.com/docs/quickbooks/mapping-objects/

> Decide which QuickBooks records your customers, products, orders and payments become, and match existing records without creating duplicates.

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](https://www.desktopaccountingapi.com/docs/quickbooks/editions-and-features/#sales-tax).

## 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](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).