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

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

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

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.