QuickBooks Sync

Once connected and configured, QuickBooks sync keeps your data flowing between Peasy and QuickBooks automatically. Here's how day-to-day sync works.

How to Get There

Click Configure (gear icon) in the sidebar, then select Integrations > QuickBooks. You can also sync from Sell > Customers, Buy > Vendors, Sell > Invoices, Buy > Bills, and supported order views.

What Syncs

The sync direction for each type depends on your settings (configured in the Setup Wizard or QuickBooks settings page). Bills, bill payments, and invoice payments each have their own direction setting.

Syncing Individual Records

You can sync specific records from within Peasy:

• Customers page — Select customers and click Sync to QuickBooks
• Vendors page — Select vendors and click Sync to QuickBooks
• Invoices page — Sync one invoice, import invoices from QuickBooks, or sync selected invoices in bulk
• Orders page — Sync a single-invoice order when Peasy can safely identify the invoice. If an order has multiple active invoices, sync each invoice from the Invoices page instead.
• Bills page — Send one bill, send selected bills in bulk, or unlink a bill from QuickBooks. The send modal previews any vendor, expense-account, freight-account, or sales-tax-account issues before pushing so you can fix them inline. Setting the freight or sales-tax account also fixes every other selected bill that needs it.

All three bulk send modals (bills, invoices, orders) share the same preflight surface: records are grouped by what needs attention, fixes can be applied inline, Continue stays disabled with a tooltip until everything is resolved, and Cancel sits in the bottom-left so it's always reachable.

Syncing Items

Items sync from Configure > Integrations > QuickBooks > Items.

Peasy is the system of record for items. Manage names, SKUs, prices, and active status in Peasy and they push to QuickBooks. Edits you make directly in QuickBooks (renaming an item, changing its price) aren't pulled back into Peasy — if you want a change reflected in both systems, make it in Peasy. The two integrity events that do still flow back are: a brand-new item created in QuickBooks (you can link, import, or dismiss it from the Items page) and a delete or merge in QuickBooks (Peasy marks the link stale so the next push prompts you to repair it).

One QuickBooks item per product family. Peasy creates one QuickBooks product/service per item family by default — not one per Buy/Sell variant. Per-line details that vary by transaction (SKU, pack size, unit price) move onto the QuickBooks invoice or bill line description. This keeps your QuickBooks item list short and easier to manage.

Existing customers who previously synced per variant are migrated to the family-level model automatically. Historical QuickBooks invoices and bills are unaffected, and any QuickBooks items that were never used stay in QuickBooks with their original transaction history.

The Items page shows every Buy and Sell variant in your catalog, grouped into filterable buckets so you can fix issues without leaving the page:

• Create — families not yet in QuickBooks; ready to push.
• Link — Peasy found a same-name QuickBooks item and will link it on sync.
• Update — already linked; price, name, or SKU has drifted and will be re-pushed.
• No category — the parent item has no Peasy category yet. Pick one in the Category column.
• Needs mapping — the category exists but is missing an income account. Set it in the Income column (or the Expense column for buy items).
• Ambiguous — two families would create the same QuickBooks name, or multiple Peasy variants point to the same QuickBooks item. These need a manual Link or rename before syncing.
• Review — QuickBooks has a same-name item with a different SKU; click Link on the row to confirm or rename to push as new.

Inline fixes from the workbench

• Set category, income, or expense account directly on the row — the Income/Expense edit changes the underlying category, so a tooltip warns you when the change affects more than one item.
• Suggest mapping (top-right, when categories need mapping) opens the AI Smart Category Mapping modal scoped to the unmapped categories. The workbench refreshes automatically when you finish, so newly mapped items appear without a manual reload.
• Per-row Actions menu — Link to a specific QuickBooks item, Unlink an existing link, or Exclude the item family from QuickBooks sync entirely. Excluded families stay in Peasy but are skipped on every sync until you re-include them.
• Column visibility — the table shows a sensible default set; toggle SKU, Family, QuickBooks SKU, QuickBooks type, vendor, and reason on or off via the column-preferences menu.

When you've resolved the blockers, click Sync Items in the top-right to push everything in the syncable buckets in one batch.

Buy and Sell variants combine when they share a name

If a family has exactly one Buy variant and one Sell variant with the same name, and their SKUs match (or are blank), Peasy creates a single QuickBooks item that combines both — purchase cost and purchase description from the Buy variant, sale price and sales description from the Sell variant. Both Peasy variants link to that one QuickBooks item.

Families with more than two same-name variants, two Buys, two Sells, or conflicting SKUs are still flagged as Ambiguous for manual review.

Line descriptions on invoices and bills

When Peasy writes the line description on a QuickBooks invoice or bill, it strips the parent name from the start of the variant name when there's a clear separator. For example, the Sell variant "Awa Bancha — bag (16oz)" appears as bag (16oz) on a QuickBooks line for the "Awa Bancha" family. If the variant name doesn't contain the parent name, or the boundary isn't obvious, Peasy uses the full variant name unchanged.

Packaging items don't sync as products

Items in the Packaging category are intentionally excluded from QuickBooks Product/Service sync. They don't appear on the Items workbench, and bill lines that use a Packaging item post directly to the bill line's expense account instead of being tied to a QuickBooks product. This keeps packing tape, bags, tins, and similar supplies off your QuickBooks item list while still recording the cost on the bill.

If you want a packaging supply to appear as a normal QuickBooks product, change its category off Packaging.

Reviewing New QuickBooks Items

When QuickBooks has items that aren't linked to anything in Peasy yet, they show up in the New Items from QuickBooks card on Configure > Integrations > QuickBooks > Items. Each row gives you three options:

• Link existing — connect the QuickBooks item to a Peasy item that already exists. Peasy shows up to three suggested matches per row with one of these reasons:
  • Exact SKU — Peasy item has the same SKU as the QuickBooks item.
  • Exact QB match — Peasy already references this QuickBooks item somewhere.
  • Exact name — names match exactly and both sides have a blank SKU.
  • Name + blank SKU — names match exactly, the QuickBooks item has a SKU, the Peasy item doesn't. Linking will copy the SKU into Peasy. The badge Adds SKU appears on these rows so you know Peasy will be updated.
• Import — create a new Peasy item from the QuickBooks data. Use this when there's no existing Peasy item to link to.
• Dismiss — hide the row. The item stays in QuickBooks unchanged; Peasy just stops asking about it.

After you click Link existing, the QuickBooks item is connected to the chosen Peasy item, and the row drops out of the new-items list automatically.

Correction Banner

If shipping or discount totals on already-synced QuickBooks invoices don't match Peasy, a yellow correction banner appears at the top of the Invoices page. These are usually invoices that synced before Peasy fully supported native shipping and discount lines.

You have three options:

• Push corrections — updates the QuickBooks invoices so their totals match Peasy.
• Review affected invoices — opens the list so you can inspect them before pushing.
• Dismiss — hides the banner without making changes.

Paid QuickBooks invoices are handled separately. QuickBooks locks paid invoices against total-changing updates, so Peasy excludes them from the automatic push and surfaces them in the banner with their own note. To resolve a paid invoice, open it in QuickBooks with your accountant: either accept the QuickBooks total as final and dismiss the banner, or reopen/remove the payment in QuickBooks first and then retry the correction. If a banner only contains paid invoices, the Push corrections button is hidden.

Automatic Sync

If you've enabled auto-sync options:

• New customers created in Peasy are automatically pushed to QuickBooks
• New vendors follow the same pattern
• Invoices can be auto-created in QuickBooks when supported invoice-send or order workflows run
• Bills can be auto-created in QuickBooks when you save a Peasy bill (toggle this in QuickBooks settings)

Importing QuickBooks Invoices

If an invoice already exists in QuickBooks, you can import it into Peasy from the Sell > Invoices page. Imported invoices appear alongside your Peasy invoices and can be used for Peasy payment collection.

When importing, Peasy checks whether QuickBooks line items are already linked to Peasy items. If items are not linked yet, Peasy prompts you to map them, create the missing QuickBooks links, or skip records that are not ready.

Orders with Multiple Invoices

Peasy treats the invoice as the QuickBooks sync target. This matters when one sales order has multiple invoices:

• Sync each invoice separately from Sell > Invoices or the invoice detail panel.
• Order-level sync is only available when Peasy can safely resolve one active invoice for the order.
• If an order has multiple active invoices, Peasy blocks the order-level sync and tells you to choose the specific invoice instead.

Shipping Fee Setup

Peasy syncs invoice shipping charges to QuickBooks' native Shipping fee field.

To set this up:

1. In QuickBooks, open invoice settings.
2. Turn on Shipping fee.
3. Make sure QuickBooks has a default shipping account selected.
4. In Peasy, refresh QuickBooks preferences if the setup screen still shows shipping as blocked.

Once set up, shipping charges on invoices sync automatically to the native QuickBooks shipping fee.

Stale Links

If a customer, vendor, or item gets deleted or merged in QuickBooks, its link in Peasy becomes stale. Peasy detects this during sync and marks the affected record as stale instead of surfacing a cryptic error.

When a stale link is detected:

• The sync pauses for that record and shows a warning with repair options.
• You can re-link the record to a new QuickBooks entry or unlink it entirely from the mapping table in Configure > Integrations > QuickBooks.
• Once repaired, the sync resumes normally.

Handling Duplicates

When syncing, Peasy checks for existing records in QuickBooks to avoid creating duplicates. Customers, vendors, and items are matched by name. Bills are matched by bill number and vendor, and invoices (including order-level sync) are matched by invoice number and customer.

The bulk send preflight surfaces these matches up front so you don't have to wait for an error after pressing Send:

• Will auto-link — If totals match, Peasy links to the existing record on send instead of creating a duplicate. The preflight notes how many records will auto-link.
• Conflict — If totals don't match, the record shows up as a conflict with three choices: Open in QuickBooks to review the existing record, Link to existing to attach without re-pushing, or Skip to drop it from this batch. Skipped conflicts can be restored from a "show again" link in the same modal.

If a Peasy bill does not have a bill number, Peasy sends a generated reference to QuickBooks. That keeps retries safe if QuickBooks created the bill but Peasy could not save the link on the first attempt.

Account Mapping Is Category-Level

Peasy maps each invoice line item to a QuickBooks income account based on the item's category — not on the item itself. The first time you sync an invoice that includes a category Peasy hasn't seen mapped yet, you'll be prompted to pick the QuickBooks income account that category should post to.

What this means in practice:

• All items sharing a category post to the same QuickBooks account.
• If you want different items to post to different accounts, put them in different categories.
• You can view and edit category-to-account mappings on the QuickBooks settings page at any time.
• Both Income and Other Income accounts are valid choices on the income side, and both Expense and Cost of Goods Sold are valid on the expense side — pick whichever matches your chart of accounts.

If you deactivate or delete an account in QuickBooks that a category was mapped to, the Configure > Categories page shows a warning banner and an inline "Account unavailable — re-map" indicator on the affected rows. Click the row to pick a new account; item sync stays paused until you do.

There is no per-item account override — if a single item needs its own QuickBooks treatment, give it a category of its own.

Bill Payment Sync

When you pay a bill in Peasy and the Bill payment ledger sync direction includes outbound sync (Both directions or Peasy to QuickBooks), Peasy automatically pushes the payment to QuickBooks as a BillPayment check entry.

Requirement: A bank account must be set under Configure > Integrations > QuickBooks > Accounting Settings > Bill payment account. Without it, the sync will be blocked and a message will explain what's needed.

Sync status on a bill: The QuickBooks chip on a bill detail page shows a yellow Payment unsynced state when a payment was recorded in Peasy but hasn't been pushed to QuickBooks yet. Open the chip's dropdown to see details and a Sync payment to QuickBooks option.

Bulk sync from Settings: If you have payments that were recorded before outbound sync was enabled, go to Configure > Integrations > QuickBooks and look for the amber "X bill payments need QuickBooks sync" banner in the Bills section. Click Sync now to push all pending payments, or Review to see them on the Payments admin page first.

Payment direction settings: The sync direction for invoice and bill payments is separate from the sync direction for the invoice or bill itself. You can set each independently:

• Invoice payment ledger sync — controls whether QuickBooks invoice payments flow into Peasy, out to QuickBooks, both, or neither
• Bill payment ledger sync — controls whether Peasy bill payments are pushed to QuickBooks, QuickBooks bill payments flow back in, both, or neither

Both default to Both directions. Change them in Configure > Integrations > QuickBooks > Sync Settings.

Invoice Dates and QuickBooks

Peasy posts invoices to QuickBooks using the invoice creation date. If your accounting workflow depends on a separate fulfillment date or service date being recorded in QuickBooks, talk to your accountant about how to reconcile the two — the dates Peasy currently sends are: invoice date, due date, and any payment dates if payments are recorded in Peasy.

Some customers wait to enable QB sync until their fulfillment-date workflow in Peasy is fully set up so that the right date lands in QuickBooks the first time. If you're in this boat, you can import existing QuickBooks invoices into Peasy first and start syncing new invoices once you're ready.

Sync Issues in the Flags Panel

QuickBooks issues that need your attention surface in the global Flags panel (the flag icon in the sidebar) — you don't have to visit the QuickBooks settings page to find them.

The QuickBooks group in Flags lists one row per category of issue:

• Token expiring soon — comes with a one-click Refresh button
• Token expired or refresh failed — links into the reconnect flow
• Sync failures and stale links — link to the Errors tab in QuickBooks settings
• Failed webhooks — when QuickBooks change events didn't process, so inbound updates may be missing
• Pending QuickBooks items — new items in QuickBooks waiting to be imported or dismissed
• Unmapped categories — categories that block item sync until you map an income and expense account

Each row links straight to the right place to fix it.

Configure Card Health Indicators

The Customers, Vendors, and Items cards on Configure > Integrations > QuickBooks show three pieces of health info:

• X linked of Y — how many of your records are linked to QuickBooks
• Z need attention (red) — failed syncs, conflicts, and stale links for that record type
• Last sync — when the most recent successful sync ran

If your QuickBooks categories aren't mapped, the Items card disables its Auto-sync new toggle and shows an inline Fix link to the categories settings — instead of letting the toggle look enabled while every sync silently skips.

Connection Health

Peasy monitors your QuickBooks connection and refreshes the authentication automatically. If something goes wrong (like an expired connection), you'll see it in the Flags panel with a one-click refresh option, and on the QuickBooks settings page with instructions to reconnect.

Good to Know

• Sync happens in near real time for most operations.
• After Peasy creates a new invoice in QuickBooks, a brief Processing in QuickBooks status appears for up to 45 seconds. This is normal — QuickBooks needs a moment before its deep link becomes active. Imported and manually linked invoices are not affected.
• You can always check the QuickBooks settings page to see the connection status and last sync time.
• If you notice data not syncing, check the QuickBooks settings page or the invoice's QuickBooks status for any error messages.
• Disconnecting QuickBooks stops all sync activity but doesn't delete any data in either system.
• Sync uses your category-to-account mapping, so make sure your categories are mapped properly in the settings.

Related

• Connecting QuickBooks — Setting up the connection
• QuickBooks Setup Wizard — Configuring sync options
• Managing Customers — Syncing customers
• Managing Vendors — Syncing vendors
• Flags — Where QuickBooks sync issues surface across the app