Our customs broker changed an XML prefix and every shipment stayed on the dock

The customs broker confirmed export declarations by sending XML messages with status and reference information. When the broker upgraded their messaging platform over a weekend in October, every shipment leaving the warehouse sat at awaiting clearance on Monday. The trucks were loaded, and the broker confirmed that every declaration had cleared.

However, the new platform wrote the status differently, using a different prefix (ns2:Status) instead of the old prefix (cus:Status). This change caused the XML reader to not recognize the status, treating it as missing and defaulting to "pending." Since there was no failure in the system, the reader acknowledged every message, and the dashboard counted messages received as normal.

After two hours, a warehouse lead contacted the broker for the fourth time, prompting the broker to send a raw message. The reader was patched within an hour and replayed the day's messages from its archive. The updated version uses a namespace-aware parser, matching elements by namespace URI and local name, eliminating the need for prefixes.

The contract tests now include rewritten messages with different prefixes, namespaces, and reordered attributes. The broker was also asked to provide advance notice of platform changes, a request they had never anticipated. Ultimately, the broker's choice of XML prefix led to a misunderstanding, highlighting the importance of focusing on the meaning rather than the spelling of XML elements.