Designing an Audit Log That Survives Cross-Border Order Disputes
A parcel arrives late, the buyer opens a dispute, and the only question that matters is: what exactly happened to this order, and when? If your answer is "let me check with the warehouse," you already lost the argument.
We run a cross-border storefront for reverse taobao / 1688 sourcing (the system is called Taocarts). Orders pass through more hands than a domestic shop: a customer, a purchasing agent, a consolidation warehouse, a carrier, and a local last-mile partner. Any one of them can change an address, split a shipment, or flag an item as damaged. Without a reliable audit trail, a dispute turns into a he-said-she-said mess.
This is a short write-up of how we designed the audit log, and the mistakes we made along the way.
Why a plain updated_at column was not enough
Our first version had a single updated_at timestamp on the orders table. It told us something changed, but not what, by whom, or from which value. That is useless in a dispute.
We replaced it with an append-only order_events table. Every meaningful state change writes a row:
order_id | event_type | actor_id | from_value | to_value | created_at | trace_id The important design choice was append-only. We never update or delete an event. When a field is corrected, we write a new event rather than overwriting the old one. That gives us a full history we can replay.
Capturing the actor, including system actors
Half the time the change is made by a person; the other half by a job. We distinguish them explicitly. actor_id can be a user, an agent, or a system token like auto_purchase_worker. During one incident, an address kept reverting and nobody could explain it. It turned out a retrying job was overwriting it. The audit log made that obvious in seconds — without it we would have blamed the customer.
Attaching a trace id across services
Purchasing, warehousing, and shipping run as separate services. A single order update can fan out into several events across them. We propagate a trace_id from the original API request into every downstream event. When a buyer asks why a package stalled, we can pull every related event with one query instead of stitching logs by hand.
What we deliberately did NOT log
We do not log full payment card data, tokens, or raw personal identifiers. Those stay in their own encrypted stores; the audit log keeps only references. Keep the log useful without turning it into a liability.
Retention and cold storage
Audit rows grow fast. We keep 12 months hot for fast dispute lookup, then archive to cold storage. Disputes older than that are rare, and when they happen the archive is still queryable, just slower.
What we learned
- Append-only beats update-in-place, every single time.
- Log the actor, not just the timestamp — "who" resolves most disputes.
- A trace id is cheap to add early and painful to retrofit later.
- Keep sensitive data out; store references instead.
If you operate a multi-party order flow, build the audit trail before the first dispute, not after. It is one of those features you never notice until the day it saves you.