A Push Is Not a Reconciliation

A push integration is optimistic by construction. It assembles a record, hands it to an interface, gets an id back and writes that id down as proof. What it does not do — what almost none of them do — is go back afterwards and ask whether the thing that arrived is the thing that was sent. For a while, ours had a reason to.

The defect was a column name

The routine that assembles purchase order lines for QuickBooks read a unit price off a property that does not exist on a purchase order line. The real column is called something else. In PHP, reading a property that is not there yields nothing, and nothing multiplied by a quantity is zero.

So every line went out with a unit price of zero and an amount of zero. The purchase order arrived. It carried the right supplier, the right document number, the right date, the right items and the right quantities. Every figure on it was zero.

The order was correct in the workspace, correct on the printed page, and zero in the books.

This is the failure mode worth naming, because it is the one that survives every check a person would think to run. Nothing threw. Nothing was logged as an error. The sync reported success and named the orders it had moved, truthfully — it had moved them. Every screen inside the workspace was right, because the workspace had the correct figures all along. The only place the fault was visible was inside somebody else's system, on a report nobody looks at until quarter end.

Fixing the code does not fix the records

Correcting the line builder was a one-word change, and it made every subsequent push correct. It did nothing whatsoever for the orders already sitting in QuickBooks at zero, because those records are not in our database. They are in yours, in a system we push to, and the only way to know what they say is to ask.

The obvious remedy — re-push everything — is worse than the problem. A blind overwrite assumes that whatever is in QuickBooks now is wrong and whatever is here is right, and that assumption is false the moment somebody has edited an order inside QuickBooks on purpose. A repair that destroys a deliberate correction is not a repair.

What a read-back actually does

So the correction is a comparison, not a push. It takes every purchase order that carries a QuickBooks id, computes what the order is worth locally, fetches the remote copy by id, and puts the two numbers side by side.

Four decisions are made in that comparison, and each of them exists to stop the repair doing damage of its own.

1. An order genuinely worth nothing locally is left alone

   If the local total is zero or less, there is nothing to correct it to, and the order is skipped before any call goes out. It is not even counted as checked.

2. A penny of tolerance

   QuickBooks rounds to two decimal places. An exact comparison between two floating point numbers would report perfectly correct orders as broken, so anything inside a cent is treated as agreement.

3. Only zero is treated as the defect

   If the remote total differs but is above zero, that is a real divergence with a cause nobody has established, and it is reported and left untouched. The repair fixes one known fault and refuses to guess at any other.

4. Lines are rebuilt only from items that exist on both sides

   A corrected order is assembled from lines whose item already carries a QuickBooks id. If that leaves no lines, the order is reported as skipped rather than pushed as an empty document.

It reports before it writes

The whole thing runs as a command, and the default is to change nothing. It prints what it found — the order number, what the workspace says it is worth, what QuickBooks says it is worth — and then tells you to run it again with an explicit flag if you want the corrections pushed.

That default matters more than it looks. A repair tool that writes on the first run is a tool nobody dares point at production, so it gets run once, nervously, on one tenant, and the other findings are never looked for. One that reports first gets run on everything, because running it costs nothing.

It can be pointed at a single workspace or swept across every workspace with a live QuickBooks connection. The sweep is declared as cross-workspace work rather than accidentally unscoped — which is the difference between a deliberate administrative operation and the kind of forgotten filter that reads records it should never have seen.

The interface lies about its own failures

One detail from building this is worth passing on to anybody integrating with a large third-party library. The QuickBooks SDK declares that fetching a record by id returns a record, and that an update returns the updated entity. At runtime, fetching an id that no longer exists returns false, and a rejected update returns nothing at all.

A type checker reading those declarations concludes that the guards around them are unreachable code, and the natural response — deleting the guard the analyser says can never fire — removes the only place a rejected write is ever noticed. Both guards are kept, and both carry a note saying exactly why they look redundant. Take the interface's word for what it returns and you will delete your own error handling on the analyser's advice.

What is in place, layer by layer

Three positions held on purpose

• A repair corrects one identified fault and reports everything else. A tool that reconciles by overwriting is a tool that will one day overwrite the correct side, and it will do it quietly across every record at once.
• The default run is read-only. Anything that writes to a system of record on its first invocation gets used timidly or not at all, and a check nobody dares run is worth less than no check.
• The comparison is on the figure, not on a status flag we control. Asking our own database whether it thinks the push succeeded answers a different question from asking your books what they actually contain.

Frequently asked questions