How to Identify Reconciled Transactions in QuickBooks Online API (With Examples)

Introduction

When working with accounting automation, one common requirement is to pull transactions in QuickBooks and verify whether they are reconciled, cleared, or uncleared.

At first glance, QuickBooks Online’s TransactionList API seems perfect for this.

However, when I began experimenting, I discovered a limitation that every developer integrating QuickBooks should be aware of.

In this post, I’ll walk you through how to retrieve and identify reconciled transactions in QuickBooks Online, using real API calls and scenarios, so you know exactly what to expect and where the gaps are.

If you are trying to identify reconciled transactions through the QuickBooks Online API, the short answer is this: QuickBooks lets you filter transactions by reconciliation status using the cleared parameter in the TransactionList report API, but it does not return reconciliation status as a separate field for every transaction in one combined result set.

In practical terms, this means you can fetch:

• only reconciled transactions,
• only cleared transactions,
• or only uncleared transactions

but you cannot make one API call and get a master list where each transaction includes its own cleared or reconciled label.

This matters when you are building accounting automation, reconciliation dashboards, or audit workflows, because you may need to run multiple API calls and combine the results on your side.

Step 1: Fetch Transactions using TransactionList API

QuickBooks provides the TransactionList report API:

GET /v3/company/{companyId}/reports/TransactionList

You can pass parameters like:

• start_date / end_date → Filter by transaction date range
• columns → Choose fields like txn_date, txn_type, doc_num, account_name, etc.
• cleared → Possible values are Reconciled, Cleared, UnCleared

That means:

• You can fetch only Reconciled transactions, or only UnCleared ones,
• However, you cannot retrieve all transactions with their status in a single call.

This limitation becomes critical when working with reconciliation adjustments in QuickBooks or when analyzing transactions across multiple accounts.

Reconciled vs Cleared vs Uncleared in QuickBooks Online

Before working with the API response, it is important to understand what these statuses mean inside QuickBooks Online.

Reconciled means the transaction has been matched and finalized during the bank reconciliation process. This is usually the final state from an accounting perspective.

Cleared means the transaction has cleared the bank or has been marked as cleared, but it may not yet be formally reconciled in the books.

Uncleared means the transaction is still open from a reconciliation point of view and has not been cleared or fully matched during reconciliation.

This distinction is important because developers often assume that “cleared” and “reconciled” mean the same thing in API logic. In QuickBooks Online, they are not the same, and that difference affects how you filter and interpret transaction data.

Step 2: Example – Reconciled Transactions in QuickBooks Online

In my sandbox, I created a Bill Payment transaction and reconciled it.

Here’s the API call I used:


GET .../reports/TransactionList?start_date=2025-09-11&end_date=2025-09-11&cleared=Reconciled


The result included the transaction confirming that the API can detect reconciled entries, but only when filtered.

Step 3: Example – Uncleared Transactions in QuickBooks Online

Next, in QuickBooks, I created an Invoice Payment and left it uncleared.

When I ran:

GET
.../reports/TransactionList?start_date=2025-09-11&end_date=2025-09-11&cleared=Uncleared

It showed up correctly in the API response.

Step 4: Handling Mixed Reconciliation Status Transactions

Here’s where it gets tricky. On the same date, I had multiple transactions:

• One reconciled bill payment
• One uncleared payment
• One cleared bill

But when fetching via API, you must query them separately by status.

There’s no way to retrieve a single dataset that contains the cleared status for every transaction.

Key Limitation

This is the main takeaway:

For auditors, accountants, or SaaS developers building reconciliation tools, this creates extra complexity because you must run multiple API calls and merge results manually.

Practical Workaround for Developers

Since QuickBooks Online does not return reconciliation status as a field in a single combined transaction dataset, the most practical workaround is to query transactions separately by status and then combine the results in your own application logic.

A common approach looks like this:

• Run one TransactionList report for reconciled transactions
• Run another for cleared transactions
• Run another for uncleared transactions
• Normalize the returned fields into a common structure
• Add your own custom status label in the final merged dataset

This approach is not ideal, but it is the most reliable option when building reconciliation dashboards, exception reporting tools, or integrations for accounting teams.

If your use case involves large transaction volumes across many QuickBooks companies, it is also worth thinking about:

• response handling and pagination,
• duplicate prevention,
• date-range batching,
• and account-wise filtering for better performance.

That way, even though the API has limitations, your integration can still produce a usable reconciliation view for end users.

Why This Matters

If you’re building automation to audit or reconcile accounts across hundreds of QuickBooks clients, this limitation can slow things down significantly.

This is especially true when handling:

• High-volume QBO transactions
• Investigating QuickBooks missing transactions
• Managing reconciliation adjustments in QuickBooks across periods

I explored a similar challenge in my previous blog post, “QuickBooks Online Reconciliation API Solutions,” where I discussed how a CPA firm with over 200 clients needed automation for reconciliation, but QuickBooks’ API restrictions forced them to build workarounds.

That experience directly informed my findings in this regard.

Common Developer Mistakes When Checking Reconciled Transactions

When developers work with reconciled transactions in QuickBooks Online for the first time, a few common mistakes show up again and again.

One common misunderstanding is assuming that the API returns a dedicated reconciliation status field for every transaction.

In reality, the cleared value works as a filter in the TransactionList report, not as a visible field in the returned dataset.

Another mistake is expecting one API call to cover all statuses together. If you want reconciled, cleared, and uncleared transactions, you need to query them separately.

It is also easy to overlook the reporting context.

Depending on the date range, account selection, and transaction type, users may think transactions are missing when they are actually being excluded by the report filter setup.

For any reconciliation-related workflow, it helps to test with small controlled sandbox scenarios first, then move to broader production datasets once the logic is validated.

Conclusion

• Use the TransactionList API to fetch transactions.
• Apply the cleared filter when you need only one type of status.
• Be aware: QuickBooks does not provide status per transaction in bulk results.
• For large-scale reconciliation projects, you’ll need to run multiple API calls (Reconciled, Cleared, UnCleared) and stitch them together.

Until QuickBooks improves this endpoint, this is the only way to identify reconciled transactions via the API.

For firms managing reconciliation at scale, dedicated reconciliation software may offer a more streamlined alternative to building custom solutions.

FAQ

How do I identify reconciled transactions in QuickBooks Online API?

Reconciled transactions in QuickBooks Online API are identified using the “cleared” parameter in the TransactionList report. Setting this parameter to “Reconciled” allows you to fetch only those transactions that have been finalized during the reconciliation process.

What is the difference between cleared and reconciled transactions in QuickBooks Online?

Cleared transactions are those that have been marked as processed or matched with bank records, while reconciled transactions are finalized during the reconciliation process. In API usage, this distinction matters because both statuses must be queried separately.

Can QuickBooks Online API return cleared and reconciled transactions together?

No, QuickBooks Online API does not return cleared, reconciled, and uncleared transactions in a single response with status labels. You need to run separate queries for each status and combine the results in your application.

Why are reconciled transactions not appearing in my QuickBooks API response?

Reconciled transactions may not appear due to incorrect filter parameters, wrong date range, or because the transactions are only cleared but not fully reconciled. It is also important to ensure you are using the TransactionList report with the correct “cleared” value.

Which API endpoint should I use to fetch reconciled transactions in QuickBooks Online?

To fetch reconciled transactions, you should use the TransactionList report API and apply the “cleared=Reconciled” filter. This is the most reliable method to retrieve reconciliation-based transaction data.

Does QuickBooks API provide a reconciliation status field for each transaction?

No, QuickBooks Online API does not provide a dedicated reconciliation status field within each transaction record in a combined dataset. Instead, reconciliation status is applied as a filter when generating reports.

Can I filter reconciled transactions by account or date in QuickBooks API?

Yes, you can filter reconciled transactions by account, date range, and other parameters within the TransactionList report. Combining filters helps narrow down results for reconciliation workflows and reporting.

What are common mistakes when working with reconciled transactions in QuickBooks API?

Common mistakes include assuming reconciliation status is returned as a field, expecting a single API call to return all statuses, and not applying correct filters in the TransactionList report. These issues often lead to incomplete or misleading results.

How do developers handle reconciliation reporting with QuickBooks API limitations?

Developers typically run separate API calls for reconciled, cleared, and uncleared transactions, then merge the data in their application. This approach allows them to build accurate reconciliation reports despite API limitations.

Does QuickBooks Online update reconciliation status in real time via API?

Reconciliation status reflects the latest state in QuickBooks Online, but it depends on when reconciliation is performed by users. The API returns updated data based on the current report filters and system state.