TenkeyBridge
← Back to blog

Marking QuickBooks Desktop Transactions Cleared Over a REST API

  • quickbooks desktop cleared status api
  • mark transaction cleared quickbooks
  • bank reconciliation quickbooks desktop api
  • clearedstatusmod qbxml
Isometric illustration of an open bank-statement ledger with green check marks in a column of tick boxes and a pen across the page.

Quick answers

Can I mark a QuickBooks Desktop transaction cleared over an API? Yes — qbXML exposes ClearedStatusModRq, and TenkeyBridge wraps it as POST /v3/company/{realmId}/clearedstatus.

Is cleared status per transaction or per line? Per split. Sending only a TxnId targets the bank or deposit-to side; adding a LineId targets a specific balance-sheet line.

Which transaction types accept it? Check, Deposit, BillPayment (check), and JournalEntry. Transfer is refused by QuickBooks Desktop itself.

How do I read cleared status back? There's no qbXML query for it, so the read-back combines a transaction read with a one-day GeneralLedger report, which carries the cleared flag per split.

Does this reconcile the account? No. Setting cleared status ticks the splits; it does not create a reconciliation record or set a statement date.


The bug that only showed up on one file

On 2026-10-26 we shipped cleared status. The endpoint set ticks correctly, the GL read-back worked in our own files, and then on a retail customer's file GET /v3/company/{realmId}/clearedstatus came back with no splits at all. Not an error. Not a 404. An empty list, for a check we had just marked cleared and could see ticked in the Desktop UI.

The cause was in the read-back matcher. That file had account numbers turned on. With that preference set, Desktop renders report account labels as 1003.01 · Checking — number, a separator, then the name. Our matcher was comparing the bare account name from the transaction read against the label string from the GeneralLedger report, so nothing lined up and every split got dropped on the floor. Fixed the same day in v125. After the fix, 44 of 44 cleared ticks verified on that file.

It is a small bug with a general lesson: on Desktop, a report is a rendering, not a data structure. Anything a user preference can change about how a value prints — account numbers, name separators, date formats — is something your parser has to tolerate. We wrote about the shape of Desktop's report layer in the report field guide, and cleared status is the place where that report layer stops being a reporting concern and becomes a correctness concern for writes.

Why bank-rec apps need this at all

If you're building anything that touches bank feeds — a reconciliation product, a cash-position dashboard, a payments app that writes checks — you eventually need to tell the accounting system "this one hit the bank." In QuickBooks Online you'd rely on the bank feed and matching. On Desktop, the cleared flag is the signal, and it's what the Reconcile window reads when the bookkeeper opens it at month end.

The difference matters for expectations. Setting cleared status is not reconciling. It ticks splits so that when Pat Owner at ExampleCo opens Reconcile, the right rows are already checked and the difference is zero. The reconciliation itself — the statement date, the ending balance, the permanent R state — still happens in QuickBooks. Your API writes put the file in a state where that takes thirty seconds instead of an hour.

The data model: status lives on splits

This is the part that surprises people coming from QBO, so it's worth being concrete.

Cleared status in QuickBooks Desktop is a property of a split line, not of a transaction. A check that debits an expense account and credits Checking has two sides, and each side has its own cleared flag. In practice the bank side is the one that matters, because that's what Reconcile looks at — but the model lets you set either.

The request shape follows that:

  • TxnId alone — targets the bank or deposit-to side of the transaction. This is what you want ~95% of the time.
  • TxnId + LineId — targets a specific balance-sheet line within the transaction. Use this when a transaction touches more than one balance-sheet account and you need to be precise about which one you're ticking.

Values are the ones Desktop understands: NotCleared, Cleared, and Reconciled. Writing Reconciled from an API is possible but a blunt instrument — it tells the file a line is permanently reconciled without any of the balancing that the Reconcile window does. Most integrations should stick to Cleared and let the human close the period.

Setting it

With the official client:

import { TenkeyBridge } from "@tenkeybridge/client";

const tkb = new TenkeyBridge({ accessToken, realmId });

await tkb.setClearedStatus({
  items: [
    { txnId: "A1B2-1700000000", status: "Cleared" },
    { txnId: "C3D4-1700000001", lineId: "2", status: "Cleared" },
    { txnId: "E5F6-1700000002", status: "NotCleared" },
  ],
});

Over raw HTTP it's the same payload:

POST /v3/company/9130350000000000/clearedstatus HTTP/1.1
Host: api.tenkeybridge.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    { "txnId": "A1B2-1700000000", "status": "Cleared" }
  ]
}

Under the hood each item becomes a ClearedStatusModRq in qbXML. This is a TenkeyBridge extension — there is no /clearedstatus resource in the QuickBooks Online API, because QBO has no equivalent concept exposed this way. If you're keeping a strict QBO-compatible code path and a Desktop-specific one, this belongs in the Desktop branch. The compatibility matrix marks extensions like this one explicitly so you can tell at a glance what won't round-trip to Online.

Partial failure

A multi-item request is not atomic. If three of five items succeed and two fail, you get three successes and two faults — same model as every other batch on Desktop, and the reason we keep saying batch is not a transaction. Read the per-item results. Don't infer success from a 200.

Which transaction types work

Settable:

| Type | Notes | | --- | --- | | Check | The common case; TxnId alone targets the bank account side. | | Deposit | TxnId alone targets the deposit-to account. | | BillPayment (check) | Credit-card bill payments behave differently; check is the supported path. | | JournalEntry | Use LineId when more than one balance-sheet line is involved. |

Not settable:

  • Transfer. QuickBooks Desktop refuses ClearedStatusModRq against a Transfer. This isn't a TenkeyBridge limitation we could paper over — the request comes back as an error from the SDK, and we surface that error rather than silently swallowing it. If your reconciliation flow depends on ticking transfers, that work has to happen in the UI.

Invoices, bills, and sales receipts aren't in the list either, which is consistent with how Desktop thinks about this: the flag belongs to things that move money through a balance-sheet account. If you need cleared status on a payment, target the deposit that contains it.

Reading it back is the awkward part

Here's the gap that shapes everything: qbXML has ClearedStatusModRq but no cleared-status query. You can write the flag. You cannot ask for it with a transaction query — it's not in the response for CheckQueryRq or DepositQueryRq.

What does carry it is the GeneralLedger report, per split. So the read-back is a composite:

  1. Read the transaction to get its splits, accounts, and amounts.
  2. Run a GeneralLedger report scoped to the transaction's date — a one-day window — to get cleared flags per split.
  3. Match report rows to transaction splits and merge.
const { items } = await tkb.getClearedStatus({
  txnIds: ["A1B2-1700000000"],
});

// [
//   {
//     txnId: "A1B2-1700000000",
//     splits: [
//       { lineId: "0", account: "Checking", status: "Cleared" },
//       { lineId: "1", account: "Office Supplies", status: "NotCleared" }
//     ]
//   }
// ]

Two consequences worth planning for.

It costs more than a read. Every getClearedStatus is a transaction query plus a report run against the company file. Reports are the slowest thing Desktop does. If you're verifying a few hundred ticks after a reconciliation push, budget real time for it and expect the timeout and retry behavior that comes with long-running report requests. Don't put a read-back in a tight loop behind a user-facing spinner.

It depends on report formatting. Which is exactly how we got the empty-splits bug. The matcher now normalizes account labels — splitting off a leading account number when the file has numbers enabled, before comparing names. If you write your own read-back against a GL report rather than using the endpoint, handle that case. The label you get is whatever the file's preferences say it should be, and you don't control those preferences.

A workable pattern

For a bank-rec flow against ExampleCo's file:

  1. Pull the statement, match lines to Desktop transactions however your product matches.
  2. Batch the matched ones into setClearedStatus in chunks — a few dozen items per request keeps individual failures easy to attribute.
  3. Collect per-item faults. Transfers will fail by design; log them for a human rather than retrying.
  4. Verify with getClearedStatus once, after the batch, not per item. One GL report over the date range beats one report per transaction.
  5. Hand off to the bookkeeper to run Reconcile. Your job ended at ticking.

If you're writing the checks as well as clearing them, be careful about ordering. A check written and cleared in the same run needs the write to have committed first, and on a hosted file with latency that's not always instantaneous. Give the write its own round trip.

FAQ

Can I mark a QuickBooks Desktop transaction cleared through an API?

Yes. qbXML's ClearedStatusModRq is the underlying mechanism, and TenkeyBridge exposes it at POST /v3/company/{realmId}/clearedstatus with the same OAuth2 and realm addressing as the rest of the API. It's a Desktop-only extension — there is no matching QuickBooks Online endpoint.

Which transaction types support cleared status?

Check, Deposit, BillPayment (check), and JournalEntry. Transfer is refused by QuickBooks Desktop, not by the bridge. Other types — invoices, bills, sales receipts — aren't addressable this way; clear the deposit or payment that moves the money instead.

How do I read cleared status back?

Call getClearedStatus, which runs a transaction read plus a one-day GeneralLedger report and merges them, because qbXML offers no direct query for the flag. Expect it to be slower than a plain read, and verify in one batch rather than per transaction.

Does setting cleared status mark a period reconciled?

No. It ticks splits so the Reconcile window opens with the right rows checked. The statement date, ending balance, and permanent reconciled state are still set inside QuickBooks. You can write the Reconciled value directly, but it skips every balance check Desktop would otherwise do.

What happens if the account label in the report doesn't match?

With account numbers enabled, Desktop prints labels like 1003.01 · Checking instead of Checking. The read-back normalizes that before matching — a fix shipped in v125 after an empty-splits response on a file with numbering turned on. If you roll your own GL-report parser, handle the prefix yourself.

Can I undo a cleared tick?

Send the same transaction with status: "NotCleared". Reverting a line already marked Reconciled is a different matter and generally belongs in the UI, where QuickBooks can warn about the consequences for closed periods. If you want to try this against a file without wiring up a Desktop install, the sandbox has the endpoint live — or start at the quickstart.