> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/finance-and-accounting/quickbooks/best-practices.md). # Best Practices ## Recommended setup


Choose the right data source	Use QuickBooks (entities) when you need raw transactional data like invoices, customers, or bills. Use QuickBooks Reports when you need formatted financial summaries like P&L, Balance Sheet, or General Ledger. Many teams use both — entities for granular data and reports for high-level dashboards.
Set the accounting method explicitly	Don't rely on the QuickBooks default. Add `accounting_method: Accrual` or `accounting_method: Cash` in the Query parameters to ensure consistency. This prevents confusion when your company default changes or when different team members set up data flows.
Use Split by for line-item data	When exporting Invoices, Bills, or other entities with multiple line items, set the Split by parameter to `Line`. This gives you one row per line item — essential for product-level analysis and accurate revenue breakdowns.
Choose Flat structure for analytics destinations	For detail reports (General Ledger, Profit and Loss Detail, Transaction List), select Flat structure instead of QuickBooks-style format. Flat structure gives you one row per transaction with all fields filled — much easier to filter, pivot, and use in BI tools.

## Data refresh and scheduling


Daily refresh for most data	Transactions in QuickBooks are typically entered during business hours, so a morning refresh captures the previous day's entries. Daily is the sweet spot for most accounting workflows.
Hourly refresh for busy teams	If multiple people are entering data throughout the day and you need near-real-time dashboards, switch to hourly refresh. This is especially useful during month-end close.
Use date filters to limit scope	Set the Where parameter to a fixed date range (e.g., `MetaData.CreateTime >= '2025-01-01'`) to pull only records from the period you need. For reports, use the Start and End date pickers to define your reporting window.
Use incremental pulls for large datasets	Avoid full historical pulls on every run. Use the Where parameter with `MetaData.LastUpdatedTime >= '2025-02-22'` (set to yesterday's date) to pull only recently modified records and append them to your destination.

## Performance optimization


Stay under the 400,000-cell limit	If a report is too large, split it into monthly data flows instead of pulling an entire year. Reduce columns by selecting only the ones you need, and filter by class, department, or customer to narrow the dataset.
Filter at the API level	Use the Where parameter to pre-filter entity data before it reaches your destination. This is much more efficient than pulling everything and filtering downstream.
Select specific columns for detail reports	Don't include multicurrency or location-tracking columns unless you actually need them — they add to the cell count and can slow down processing.

## Dashboard accuracy


Keep accounting method consistent	Make sure all data flows feeding the same dashboard use the same accounting method (Cash or Accrual). Mixing methods produces misleading totals. Add `accounting_method: Accrual` (or `Cash`) explicitly in Query parameters.
Use Class and Department IDs, not names	When filtering reports by class or department, use the entity IDs (numbers), not the display names. First export the Class or Department entity to get the ID-to-name mapping.
Align report periods when combining data	When combining data from multiple reports (e.g., P&L Summary + Balance Sheet), ensure the date ranges match exactly. A one-day mismatch can cause reconciliation issues.
Budget vs. actual comparisons	Combine the Budget entity (for budget figures) with the Profit and Loss Summary report (for actuals). Note that budget line items may need additional processing due to their nested format.

## Common pitfalls to avoid {% columns %} {% column %} **Do** * Set `accounting_method` explicitly in Query parameters * Use `Active IN (false, true)` when you need inactive records * Use `Split by = Line` for invoice line-item exports * Choose Flat structure for BI tool destinations * Split large reports into monthly data flows {% endcolumn %} {% column %} **Don't** * Don't assume QuickBooks returns inactive records — it doesn't by default * Don't expect custom QBO reports to appear in Coupler.io — only the predefined report types are available * Don't use Display columns by Class and Month simultaneously — the API only supports one grouping dimension at a time * Don't ignore the 400,000-cell limit — your data will be silently truncated * Don't use OR in the Where parameter — only AND is supported {% endcolumn %} {% endcolumns %} {% hint style="danger" %} **Custom reports are not supported.** Coupler.io pulls from QuickBooks' predefined report types via the API. Custom reports you've created in the QuickBooks UI won't appear in the report dropdown. Instead, use the closest predefined report and apply query parameters (class, department, customer, date filters) to get equivalent results. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/finance-and-accounting/quickbooks/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.