Designing the Customs App


“It’s not a logical straight through process. So you almost are tricking core to perform with what you want to happen in netchb… if brokers aren’t careful…you’ve created an incorrect entry” - Flexport broker"


Capturing the Flexport Customs Workflow

My previous research and visioning directly led to this project. Since we knew brokers workflows were broken across apps and we would be capturing their workflow we intended to see how much work we could turn into product process and then automated.

We did an analysis of how many shipments might actually be automated in the near future and found that 40% of shipments fell into the level 1 category.

The level 1 category means a customs entry on a shipment doesn’t require additional information that would require human intervention because we need to communicate with the client.

Level 1 shipments could be conceivably automated if we could build the additional software to verify that the data entered info was correct.

So it was decided between me and the PM that we’d design and build a product that would set us up to automate 40% of customs shipments in the future thus reducing cost-to-serve your clients for the business, and improve filing accuracy.


High level broker filing workflow

As mentioned before a broker’s process is broken across different apps and many different screens. Ultimately, the desired state would be to bring this workflow into one flow with one app experience.


Current state of affairs

The current work space for brokers is crammed into the corner of our shipment view which is primarily used by operations to keep shipments updated. Brokers are forced to use a little corner of the UI to get their work done. It’s very inefficient having a generalist view, so we wanted to make a dedicated workspace for brokers.

customs core.png



I always start my process at Flexport with research. The depth of knowledge required in US Customs simply means our PM can’t dream up all the critical edge cases, especially on the customs team. I verify that our assumptions align with compliance, and learn more US Customs and the users.

We had a list of data points that we needed to cross-reference with brokers to makes sure we were capturing all the right information for a broker to file with US Customs. Simple if all brokers followed the same process, but due to the complex nature of customs data brokers put different levels of emphasis on data.

The goal was to discover watch brokers file and discover edge cases for what information is needed universally for brokers to file a level 1 shipment.

The previous designer on customs team had done some previous research into redesigning the customs workflow. I started with a high contrast paper prototype as a starting point.




On the left is the broker’s screen. They have to do a lot of checking information across documents. Typically they open docs on the left and compare to data in our app, called core.

“I would also check the invoice summary aka invoice number and it shows all the classifications from core. I’m now double checking the transmission in the invoice summary. A weight could pulled incorrectly. This is the last check for data entry errors, and making sure core is not messing up.” - Broker


Filing entries is about double checking data and should be automated.

“I check Manifest query to match number. I double check Manufactuer code to make sure it’s correct. Then I provide this manufacturer info in this cargo release form. This fields gets populated by ISF, but because its Canadian rail it goes into Canada and doesn’t require an ISF.”



Defining the requirements


My research sculpted the requirements for the product. Here’s a screen of the tables of data I was working with to check off items as as required or not, and call out edge cases.

It’s critical we get all these right, and while it would of been great had our PM could define all the requirements it was just too deep and required a multi-pronged effort to catch everything.




Every decision has a trade off and debating on the benefits of each decision without clarity of direction can lead to a lot of lost time figuring direction. With a vision set from prior work I collaborated with engineering and product to decide on our principles of how the design decisions for the product would be prioritized.



Remove irrelevant data

The problem with the existing workflow is that it exposed 100s of data points while only a few were actually relevant to the broker. If a data point is not critical for level 1 shipments we’d exclude it.



Discourage unnecessary verifying

I learned from my work on the Flexport LCL team that even if you change a workflow to a new one that doesn’t mean they’ll kick the habit of checking their work. If the interface was completely editable when opened it makes it easier to fall back in the pattern of changing data. This UI should discourage editing by not being ready to edit until a user wanted to.



The system should do verifying instead of the user

To automate work we should have the software check on behalf of the broker so they could eliminate that from their work to be done. As we chip away at automating these checks we could conceivably get to a place of automatically filing entries if data integrity was high.

This would be an iterative process as we built out the entire framework.


The interface directs the user to work

Part of the problem with so much information is knowing what work needs to be done. The interface should direct the eye to what information needs work. This shows itself in the smart fields, and also the highlight when the user is looking at a document.



Ideating direction and components

Once research was complete and principles were established it was clear there’d be a few essentials experiences and components to the app.


Thoughts on Layout

Given the heavy dependence on documents that it would be a permanent fixture in the UI with an affordance to switch between them.

Half the screen real estate would be dedicated to documents and the other half data. I had a few ideas on how we could layout the information.

Ideas on directions

  • Break up the process into steps to reduce the information density.

  • Having everything all in one place - the power user experience.

  • Grouping information to each document.

  • Grouping information by the broker’s mental model of categories.


The challenge with grouping data is that different documents had the same data, so you could re-use a document on different areas. This navigator would allow for quick swapping between documents to verify data.


Data visualization of the different documents and their overlapping required data.

The overlapping relationships means that while some data could be checked by one document, a lot of data has to be cross-referenced by other sources.

Invoice Summary

The invoice summary contains all the necessary information for each line item that is going to be classified and filed. Though it could do with a future redesign, we decided to do minimal changes by removing unecssary data and preserving the core functionality for design and engineering velocity on more important experience improvements.


Header Info

The header info section contains the data that needs to be verified by brokers. Not all info needs verification all the time, but it provides important context.

The route info can help a broker know if the shipment is being imported directly to a port or if it is being imported into the US through an “inland” port which requires additional data.

US Customs watches data closely, and they need to match all documents and with US Customs system. A conflicting data element anywhere in the data chain could lead to a customs hold.

Note the alert and the check followed by an explanation below the data elements. I started to call these smart fields.


Introducing Inline Editing


In the traditional Flexport app, edit mode makes everything in view a field. The sheer amount of data a broker sees with that many fields adds a lot of extra visual weight.

I treated this part like I treat data visualization projects, reduce the data to ink ratio where it makes sense.

It would also discourage editing information and hopefully checking if it’s necessary.

Save/Cancel - Traditionally inline editable fields save when you click out or when you hit enter. This consumer experience works fine because it isn’t important that the data be exact or intentional.

In customs world, all data that is changed must be intentional. Any small changes should be saved/caceled, because of compliance risks.


Introducing Smart Fields

“Where is the info coming from? Such as manifest quantity? How did it draw that number when the numbers are incorrect?” - Customs Broker

Brokers habitually distrust the data they’re given, because that 2% of time it’s wrong they get burned. Data integrity is so important - they’d rather double check then get it wrong.

If our system knows the data is correct, the broker will not trust it because previous experience tells them otherwise.

Smart fields were introduced into user testing to see if we could build trust in the system and prevent extra work by revealing the source of the data and what we did to verify it is correct.



Prototyping and usability testing

Early Prototypes


The first prototypes tried breaking the workflow into steps, tieing the documents to each step. The trouble was that multiple documents applied to some steps and data would be needed in different steps.

“Because it has all the info in one screen, I have to fill out stuff first, and then go to the next screen to review. Where as this one has everything upfront and I can just verify all the things. I could file the entry directly form this screen.” - Customs Broker

Overall the feedback was very positive about having a dedicated space with the documents and a preference to have all the data in place. Typical power user requests.

Building and refining experiences with prototypes


I built my later prototypes in Framer, giving them a high degree of realism and interactions. This was really helpful in seeing what real-world reactions.

They looked visually belieavable, but weren’t intended to be final visual designs.

Some inspirations of interactions came out of testing that were added later.

The later prototypes continued to test workflow, but now it was workflow within one space rather than breaking up the flow into individual steps.


Thats cool, it points out different information, and fields to look for on each document. I like it, its kinda like a little guide, it helps you along the way. It’s good to see the sources of all your info.” - Customs Broker

After testing many iterations of concepts, we eventually arrived at a solid prototype that made it ready to progress to the next step by validating concepts and solidying which ideas to keep.

The route and shipment data layout were changed later to divide the sections more clearly, and visual design was needed to clean things up, but we got the direction for implementation.

“I really like how all of this info is on the left side, this is the essential info to make sure its filed accurately.” - Customs Broker



UI design, Documentation and Implementation



After defining the interactions to a greater degree I sat down with engineering to implement. I provided spec’d details of states and also discussed layout logic. My time learning a little of a javascript language called React helped me communciate that we should use fractions on the layout so it adjusts the fields based on the data that’s entered.



Thorough research setup this project for success. By shadowing brokers and having a vision prior I already got a sense of where things could go. Jumping into paper prototypes, and rough prototypes early on really helped dissect the nuances of the behaviors and requirements for this product.

There was a lot in this product to go from zero to one and we broke it out into parts for future releases. This started the ball rolling for us to begin the process of matching the Flexport customs broker workflow.

The reaction from the business was estatic, we were making progress towards a future specialist experience. This project later was given additional support to demonstrate that we could create dedicated specialist experiences over generalist ones.

While still not feature complete to match broker’s work to be done. Future projects chipped away at getting to feature parity of the old workflow, and improving it where we could.