A customs hold is a record of a decision made by someone else, plus two deadlines you can compute but cannot enforce, so the pipeline should store the observable events and derive the rest.
Engineers who build shipment pipelines are used to status enums they own. A carrier confirms pickup, a warehouse confirms pack-out, a last-mile provider confirms delivery. A customs hold breaks that pattern. The decision to detain or release is made by U.S. Customs and Border Protection, not by any service you can query, and no endpoint returns the current hold state. What the pipeline can do is record what it observed, store the timestamps that start each clock, and compute the deadlines the regulation already defines. The rest is presentation, and the presentation has to be honest about what is unknown.
A hold is not a status flag
The trigger for the short clock is not the arrival of a container. Under 19 CFR 151.16(b), merchandise counts as presented for CBP examination when it is in a condition to be viewed and examined by a CBP officer. The same provision says that delivering a cargo van, a container or another instrument of international traffic to the examining officer is not by itself presentation of the merchandise.
That distinction matters to the data model. If the pipeline stamps presented_at when the container gate-in event arrives, it starts the clock early and every derived date is wrong. The observable event you can defend is narrower: the goods reached a condition in which an officer could look at them. In practice that is a human judgment made at the port, so the field should be nullable and set from an operator confirmation or a document, not inferred from a gate transaction. A container present at the terminal and a container presented for examination are two different facts.
Two clocks, not one
19 CFR 151.16(b) leaves CBP five business days after presentation before it has to say release or detain. 19 CFR 151.16(e) requires a final determination on admissibility within 30 days from the same presentation date. One window is counted in business days, the other in calendar days, and both start at the same event.
A cron expression that adds five days is wrong five days out of seven. Business days exclude weekends and federal holidays, and the rule does not give you a holiday table. Store the presentation date as a date, not an instant, and compute the two deadlines with an explicit business-day calendar that is versioned alongside the record. When the calendar changes, the stored deadline should not silently move. Keep the computed deadline and the calendar version that produced it.
The 30-day window is the simpler of the two, but it is not a promise that a decision arrives on day 30. It is the point at which the rule changes what silence means.
The notice is an inbound payload with five fields
When CBP decides to detain, or fails to release inside the five business day window, 19 CFR 151.16(c) requires a notice going to the importer or another party with an interest inside five business days of that decision or of the failure to release. The notice is not a final admissibility ruling. It has a fixed shape with five fields: when the goods were presented for examination, why the officer stopped them, how long the hold is expected to run, what tests or inquiries are in prospect, and what information, if supplied, would hurry the outcome.
The fifth field is the only one that gives your system something to do. The other four are context. Model the notice as an object with five named fields, keep the raw document, and map field five to an operator task with its own status. A notice that arrives with field five empty is still a notice, and the task should say so rather than inventing a request. Field three, the anticipated length, is CBP's estimate. Display it as an attribute of the notice, never as your system's prediction.
type HoldState = "presented" | "notice_received" | "final_determination" | "deemed_excluded";
Silence is a state
If no final determination is made within 30 days of presentation, 19 CFR 151.16(f) treats the failure as a decision by CBP to exclude the merchandise, and that deemed exclusion can be protested. The regulation also allows a longer period where a statute specifically authorizes one, so the 30-day boundary is the default, not an absolute.
For the pipeline this means a hold record cannot sit in a pending state forever. At the computed 30-day boundary the derived state becomes deemed_excluded unless a final determination was recorded first. That transition happens without any inbound event. It is a job that reads stored dates and writes a state change, and it should be idempotent because it will run more than once. Do not render a spinner for a hold that the regulation has already resolved by silence.
What the schema must store to answer a notice later
A notice can ask for information about what was in the box, and the answer has to come from records made before the question was asked. Store per-SKU counts and weights captured when the goods arrived at the facility, not reconstructed afterward. Store packing changes as new dated records rather than overwriting the prior configuration, so a later question about what the carton contained on a given date has an answer.
The same logic applies to the presentation date, the notice receipt time, the raw notice, and every deadline computed from them. An append-only event log with a projection for current state costs more to build than a mutable row. The trade-off is that a mutable row cannot tell you what it said last week, and a detention notice is exactly the kind of question that arrives after the fact.
Failure modes worth designing against
A webhook that never fires is the first. The notice may arrive as a document through a broker, so the system needs a manual intake path with the same schema as the automated one.
A state that waits on a human at the port is the second. Presentation for examination depends on an officer's judgment, so the pipeline should accept that field as an operator input and refuse to guess it from gate events.
A UI that shows an ETA you do not have is the third. The anticipated length in the notice is CBP's number. Anything your interface displays beyond that is an invention, and an operator who trusts it will miss the 30-day boundary.
What the operation records
FulfillNexa by SBT (fulfillnexa.com) receives freight at its own China sites, Suzhou being the largest at 13,000 square meters. Weight, count and packing configuration are captured per SKU at the receiving door, and a packing change appends a dated record instead of rewriting the old one, which is what makes an append-only design practical at this layer. The output is evidence for whoever has to answer a notice. It is not a legal or valuation position, and the declared number stays the customer's.
Top comments (0)