Case Study: Cutover from a Legacy ERP to a New Order API
Updated
A fictional wholesale distributor replaces nightly CSV imports with a new order API while keeping the legacy ERP running - duplicate events and retries make the migration an idempotency exercise.
This is a fictional training case written for learning purposes. It does not describe a real client engagement.
Situation
A fictional distributor ("Nordwind Supply") runs a 15-year-old ERP. Sales wants the new e-commerce API live; finance refuses any double-posted order. The old integration imports nightly CSVs; the new one must operate in parallel for a month.
The delivery arc
- Discovery: order volume ~4,000/day; exceptions ~3%; ERP has no real-time API - only a message file table you may poll.
- Brief: zero double-posted orders (hard), <5 min latency for 95% of orders (target), daily reconciliation report (hard).
- Design: poller with watermarks; idempotency key
orderId + version; unique constraint in the new API's DB; ERP writes stay canonical until cutover. - The failure that taught: the ERP's message table re-emitted the same order with a new timestamp after manual edits - the naive watermark missed it. Fix: business key + content hash, not timestamps.
- Cutover: shadow week comparing API results vs CSV import diffs; discrepancy list reviewed with the ops lead; flag flip per order type, not all at once.
- Handover: reconciliation runbook, DLQ re-drive procedure, two recorded sessions with the ops team.
What learners should extract
- Idempotency on business keys, not timestamps (pattern reference).
- Shadow-run cutovers beat big-bang (delivery patterns).
- Reconciliation reports are trust artifacts, not optional chores.
Practice version
The Integration Delivery capstone uses a similar fixture with injected duplicates and an edit-after-ship trap.