Guide / Digital Systems & Commerce
E-commerce Architecture Is Mostly About Keeping Systems from Lying to Each Other
Catalogue, prices, orders and stock overlap across commerce systems. Decide who owns each fact, how changes travel and how conflicts are detected and repaired.
A product is available in the store, unavailable in the warehouse, and still listed on a marketplace. All three systems may be functioning exactly as designed. They simply hold different versions of a fact and disagree about who has the authority to change it.
That is why commerce architecture cannot begin and end with API connections. A connection moves data. It does not establish ownership, define freshness, or decide what to do when two legitimate processes produce conflicting updates.
I would start an integration design by writing down the facts the business relies on and the rules that make those facts believable. The boxes and arrows become much more useful after that discussion.
The hardest question is often not “how do we sync this?” but “who is allowed to be right?”
Draw authority before data flow
Consider a hypothetical retailer with a catalogue system, an order service, an inventory service, a storefront, and a marketplace adapter. This is a conceptual split of responsibilities; it does not require five separately deployed applications.
Catalogue owner --> Storefront --> Order owner
| ^ |
v | v
Marketplace adapter Inventory owner Reservations
| ^
v |
External marketplace Warehouse observations
Inventory owner --> Storefront and Marketplace adapter
Reconciliation compares recorded operations and current state.The arrows show expected movement, but each needs a contract. The catalogue owner may control product descriptions while the inventory owner controls availability. The warehouse supplies observations about physical handling. The order owner records what a customer requested and the subsequent order lifecycle.
One system does not need to own every fact. In fact, assigning the entire operation to one nominal source of truth can hide important distinctions. The useful unit of ownership is the fact or decision, not necessarily the application.
For each fact, name who can create it, who can revise it, and who only receives a copy. Then define what a receiving system should do when its local view is stale.
Give words precise meanings
“Stock,” “price,” and “order status” can each conceal several values. Stock might mean physically counted units, units available to promise, or units allocated to one channel. Price might mean a base amount, a channel-specific offer, or the amount agreed when an order was placed.
An integration that maps fields by similar names can therefore be wrong while passing every schema check. The payload is valid, but the business meaning has changed in transit.
Write a short definition beside each shared field. Include its unit, relevant timestamp, owner, and whether it describes a current state or a historical event. An order’s agreed price should not silently change because the current catalogue price changed later.
Examples help reveal ambiguity. Ask what the value should be during a reservation, after a partial shipment, or when a return has been received but not inspected. If the team cannot agree on the answer, writing the connector first will only encode the disagreement.
Design for repetition
Networks make it possible for a sender to miss a response after the receiver has completed the operation. A retry can then repeat work that already happened. The integration must distinguish a new business operation from another delivery attempt for the same operation.
Stripe’s idempotent request documentation provides a concrete example of an API contract that uses keys to recognize repeated requests. Its behavior is specific to that API. Other destinations need their own documented mechanism or an application-level strategy; an arbitrary request header does not make every service idempotent.
A stable operation identifier should travel through the integration and appear in useful diagnostic records. Where possible, the receiver can record the operation and its effect together. Where that is not possible, the design needs a way to inspect the destination before repeating an uncertain write.
Do not confuse duplicate delivery with duplicate customer intent. Two identical purchases may be legitimate separate orders. Deduplication needs the identity of the operation, not merely a comparison of similar payloads.
Assume updates can arrive late
The order in which events are produced is not always the order in which they are processed. A delayed catalogue update can overwrite a newer value if the receiver accepts every arrival as current truth.
Choose an ordering rule appropriate to the fact. A source-controlled version can help a receiver reject older state. A timestamp may help with freshness, but clocks and concurrent writers complicate using time as the only authority. The design should state which source assigns the ordering information and what happens when it is missing.
Some updates represent events that must remain in history; others represent replaceable snapshots. Treating a shipment event like a current-state snapshot can lose an important transition. Treating every snapshot as an independent action can repeat side effects.
This distinction also affects recovery. Replaying a history and fetching the current authoritative state are different operations. Either can be appropriate, but the receiving process must know which it is performing and which effects it is allowed to produce.
Notifications are not a reconciliation strategy
A webhook can make updates timely, but it should not be the only way to discover disagreement. WooCommerce’s webhook documentation describes delivery behavior and statuses, including disabled webhooks. An operator therefore needs visibility into the delivery mechanism as well as the records it is intended to synchronize.
For a critical integration, keep a reconciliation path. It might compare a bounded set of recently changed records, inspect operations without a confirmed outcome, or periodically verify a summary against the owner. The method should fit the cost and consequences of stale data.
A reconciliation result needs more than a mismatch count. Identify the affected fact, the expected authority, the observed versions, and the permitted repair. Some discrepancies can be corrected automatically. Others require a person because both values reflect legitimate but conflicting decisions.
Avoid a repair process that writes both sides until they happen to match. That can erase evidence and create update loops. The repair should follow the same ownership rule as ordinary processing.
Make uncertainty visible to the next decision
A stale inventory view should not look identical to a fresh one if the difference changes what the business can safely promise. The interface may need to show pending confirmation, restrict a risky action, or route the case to review.
The appropriate behavior depends on the product and the cost of a mistaken promise. A low-risk catalogue description may tolerate delayed propagation. A scarce item’s final unit may require a stronger reservation mechanism. Calling both “eventually consistent” does not explain the operating policy.
Inventory deserves its own consistency model because the number is tied to competing claims and physical events. The same general principle applies elsewhere: freshness is a property of a fact in a decision, not a universal timeout chosen for the whole application.
Give users and operators enough information to act without exposing unnecessary implementation detail. “Awaiting warehouse confirmation” is usually more useful than an internal queue name. The system can keep the technical trace behind that understandable state.
A reliable integration explains disagreement and repair as clearly as it explains the successful transfer.
Test the contract at its weakest moments
The happy path confirms that compatible payloads can move through the system. The more revealing tests delay a response, repeat an event, reorder updates, remove a required field, or stop processing between two external effects.
For each case, ask what the next observer should see and what the next attempt should do. The answer should follow the documented ownership and recovery rules. If it depends on an operator remembering an undocumented trick, the design is not yet complete.
A small contract test suite and a rehearsed reconciliation procedure can provide more confidence than a large architecture diagram. The diagram remains useful, but only when its arrows correspond to behavior the system can demonstrate.
The aim is not instantaneous agreement everywhere. It is a controlled relationship between authority, delay, and repair. Commerce systems become easier to trust when disagreements are expected, detectable, and resolved according to rules that the business can understand.