Shopify return shipping tax: pending null is different from a finalized zero
Estimated and finalized tax have different calculation times. Reconciliation must preserve finalization state as well as amounts.
What disappears when an empty amount is filled
Unfinalized tax and no tax are different states. Replacing null on an unprocessed return with 0 can put an undecided amount into the ledger as if it were final. A transformation intended to tidy a support display can propagate into reconciliation data and leave the next operator unable to tell what is still pending. [1, 2, 3]
Separate fields for estimates and final amounts
Shopify's 2026-10 change announcement distinguishes estimated return-shipping tax in taxAmountSet from finalizedTaxAmountSet, fixed when the return is processed. The latter is null before processing and 0 when no tax applies. If the tax provider calculates a different amount at processing time, the estimate and final amount can differ. Their disagreement is not automatically a data error. [1]
The reconciliation table needs more than amounts
The reconciliation owner should retain estimated and finalized tax in separate columns. If a final value is populated before processing, compare the processing state with the source response and hold it from reconciliation. Separate shop and presentment currencies too. Align states and amounts from different observation times to a consistent processing boundary first. Copying an estimate into a temporary final column obscures whether a later difference is a real recalculation or an artifact of transformation. [1, 3]
Check presence before interpreting 0
For an illustrative unprocessed return, expected finalized-tax presence is false. Retaining source null as false preserves the pending state. Filling 0 and changing presence to true loses that state and fails the check. Conversely, source 0 after processing can be a finalized no-tax result. This fixture neither calculates actual tax nor determines the jurisdictions and conditions where tax applies. [1, 3]
A conditional state contract for Truthound
RowLevelValidator in Truthound Core 3.3.2 accepts a row_validator callback that can identify contradictions between prepared processing state and final-value presence. Operators define that condition from the specification; it is not a model that infers tax rates. If source nullness or processing time has been lost, first recover whatever supporting evidence remains. Display pending amounts separately and reconcile against finalized amounts after processing. Passing the data check is not certification of tax compliance. [1, 2, 3]
Application conditions
From 2026-10 or later responses, preserve processing state and source nullness together, keeping shop and presentment currencies separate. Align records whose processing and observation times differ before comparison.
Alternatives
Display an explicit pending state before finalization and reconcile against the finalized amount received after processing.
Limitations
Truthound does not calculate tax or certify tax compliance. Estimates and final amounts can differ because of the provider's calculation time, so do not impose simple equality.
Evidence
- Event checked
- Subject checked
- Modified
