Set up QuickBooks Online with FlintPOS

Use this guide to connect QuickBooks Online, create the required chart-of-accounts records, map FlintPOS activity to the right GL accounts, choose what syncs, and run a safe first test.

What FlintPOS syncs

FlintPOS is designed to keep operational work in FlintPOS and accounting records in QuickBooks. The integration currently supports these sync paths:

• Orders to QuickBooks: unpaid FlintPOS orders sync as QuickBooks invoices; paid FlintPOS orders sync as sales receipts when possible.
• Payments both ways: FlintPOS payments can push to QuickBooks, and QuickBooks payments can come back to FlintPOS through webhooks and scheduled sync.
• Customers: customer names and account identity are created or matched in QuickBooks so orders attach to the right customer.
• Products and inventory items: FlintPOS products can create or update QuickBooks items, including sale price, cost, SKU/name data, inventory quantity, and FlintPOS product photo URLs in the item description.
• Customer credits: unapplied QuickBooks credit memos can become FlintPOS store credit. FlintPOS returns to store credit can create QuickBooks credit memos.
• Voids and deleted payments: QuickBooks payment voids/deletes reopen FlintPOS balances, and QuickBooks invoice voids can mark the FlintPOS order void with a processor note.
• Sales tax collected: FlintPOS can push tax as a visible line item and, when mapped, reclass it to a sales-tax liability account so it is not treated as normal sales income.

1. Connect QuickBooks from FlintPOS

1. Open Settings > QuickBooks in FlintPOS.
2. Verify the connection card says QuickBooks developer app configured.
3. Copy the webhook URL shown in FlintPOS and confirm it is saved in the Intuit app if you manage the developer account.
4. Click Connect QuickBooks.
5. Sign into QuickBooks Online and choose the company to connect.
6. Approve the connection. FlintPOS should show the connected company name and realm ID.

If the OAuth tab closes but FlintPOS still says Connecting, refresh the FlintPOS app window. The server may already be connected; the page refresh reloads the connection status.

2. Create the required QuickBooks accounts

QuickBooks will reject synced products, invoices, payments, or tax entries when required accounts are missing or mapped to the wrong type. In QuickBooks Online, open Settings gear > Chart of accounts > New and create or confirm these accounts.

3. Map accounts in FlintPOS

1. Return to Settings > QuickBooks in FlintPOS.
2. Refresh the page after creating accounts in QuickBooks.
3. Use the GL Account Mapping dropdowns to choose the matching accounts.
4. Save settings before running any manual or automatic sync.

If a dropdown is empty, QuickBooks has not returned a valid account of the required type. Create the account in QuickBooks, confirm the type, then refresh FlintPOS.

4. Choose sync options and frequency

The QuickBooks settings panel lets each tenant decide what should sync automatically.

• Scheduled sync: runs selected QuickBooks tasks automatically.
• Sync frequency: choose how often FlintPOS checks for pending work. Webhooks still handle many QuickBooks-side events, but scheduled sync is the safety net.
• Orders to QuickBooks: sends eligible FlintPOS orders to QuickBooks.
• FlintPOS payments to QuickBooks: sends payments collected in FlintPOS to QuickBooks.
• QuickBooks payments to FlintPOS: imports QuickBooks payment activity and updates FlintPOS order balances.
• Bulk customers/items: pushes existing customer and product records. Use carefully on large catalogs because QuickBooks may throttle requests.

5. Sales tax handling

FlintPOS calculates sales tax from FlintPOS rules and the order context. QuickBooks Online has its own automated sales tax system, but we learned during testing that relying on QuickBooks line tax codes can reject requests or lose FlintPOS jurisdiction detail.

For reliability, FlintPOS sends tax collected as a separate line named FlintPOS Sales Tax Collected. The order memo includes FlintPOS tax context, including jurisdiction details when available. If the Sales Tax Liability Account is mapped, FlintPOS can reclass that amount out of sales income and into the liability account.

For jurisdiction reporting, use FlintPOS tax reports as the operational source because they preserve the state, county, city, and delivery-address context that created the tax. Use QuickBooks for accounting totals and reconciliation.

6. Fresh QuickBooks company checklist

A fresh QuickBooks company may be missing sample accounts and items. Before the first sync:

• Create the required GL accounts above.
• Map every required account in FlintPOS.
• Run Push Items only after Inventory Asset and Cost of Goods Sold are mapped.
• If QuickBooks was cleared or reset, old mapped IDs may no longer exist. FlintPOS will attempt to detect missing customer/item/account IDs and recreate or remap them.
• If QuickBooks throttles item sync, wait for the automatic retry. Large item pushes can take multiple batches.

7. Recommended first test

1. Create a test customer in FlintPOS with a clear name, such as QBO Test Customer.
2. Create one taxable inventory product with cost, sale price, SKU or clear product name, and starting quantity.
3. Create an unpaid FlintPOS order and sync it. Confirm QuickBooks shows an invoice with the customer attached, product line, tax line, memo details, and correct total.
4. Mark that invoice paid in QuickBooks. Confirm FlintPOS updates the order balance and payment method.
5. Create a paid FlintPOS order with cash, check, or card. Confirm it automatically syncs to QuickBooks as a paid transaction.
6. Edit the FlintPOS product price or quantity, then create another sale. Confirm the QuickBooks item updates for future transactions.
7. Create an unapplied QuickBooks credit memo for the test customer. Confirm FlintPOS adds store credit instead of double-applying it to an open order.
8. Void or delete a QuickBooks payment and confirm FlintPOS reopens the matching balance with a clear processor note.
9. Void the QuickBooks invoice or sales receipt and confirm the FlintPOS order records the QuickBooks void state.

Troubleshooting quick reference

• Redirect URI invalid: the Intuit production Redirect URI does not exactly match https://app.flintpos.com/api/quickbooks/oauth/callback.
• GL dropdown is empty: create the account in QuickBooks with the required account type, then refresh FlintPOS.
• Invalid Reference Id: QuickBooks data was deleted or reset. Refresh accounts and rerun sync so FlintPOS can recreate or remap missing customers/items.
• Required ExpenseAccountRef or IncomeAccountRef missing: map Income and Cost of Goods Sold accounts before syncing products.
• Invalid Line TaxCode: FlintPOS should use the tax line fallback for US companies, not raw QuickBooks tax-code IDs.
• ThrottleExceeded: QuickBooks rate-limited the request. Wait for the automatic retry or run the manual sync again later.
• Connected but app still says Connecting: refresh the FlintPOS app window. The status polling fallback should prevent this on current builds.