Customs reopen flow

Reopen is the admin-only reversal of a customs declaration that was released in error. It's deliberately gated and audited — reopening should be rare.

When to use

Legitimate reopen scenarios:

• Wrong declaration released — the broker released the wrong job against your customs account.
• Data error caught post-release — the HS code or declared value was wrong and customs is willing to accept a corrected declaration.
• Internal process failure — an operator clicked Release by mistake before the actual physical release.

Not a reopen scenario:

• Amendment to a released declaration — customs authorities usually have an amendment process; use that, not reopen.
• Customer dispute — the declaration was correct; the customer's objection is a commercial matter, not a customs one.
• Reworking charges — adjust the invoice, not the declaration.

The permission gate

Only TENANT_ADMIN or ADMIN roles can reopen. Other roles (even customs operators) see the button disabled with a tooltip explaining the gate.

This is deliberate — reopen touches high-risk state (release timestamps, post-release workflow, deposits). Routing through admin prevents accidental clicks.

Step-by-step

1. 1
   As a TENANT_ADMIN, open the released declaration's detail page.
2. 2
   Scroll to the after-release panel → Reopen Declaration button (red outline, bottom right of the panel).
3. 3
   Modal opens — enter a reason of at least 10 characters. This is stored and shown on the reopened declaration banner.
4. 4
   Click Reopen. The declaration transitions: released → reopened. release_date is cleared. post_release_status is reset. reopen_count increments. An audit-log row is written with actor + reason.
5. 5
   Declaration is now in reopened status. A yellow banner shows the reopen reason + timestamp + total reopen count.
6. 6
   Correct whatever was wrong — edit lines, add permits, fix values, etc.
7. 7
   Transition reopened → cleared when the correction is complete. Then cleared → released again to restart the post-release workflow with a fresh 14-day docs clock.

What happens to deposits on reopen

Nothing automatic. Deposits recorded against the declaration remain. If the reopen means you're double-paying a deposit (e.g. you posted a guarantee on release 1 and now need another on release 2), record the second deposit explicitly — they're tracked independently.

Audit trail

Every reopen is recorded with:

• Actor (which admin).
• Reason (the required text).
• Timestamp.
• reopen_count increment.

View via Settings → Audit Log → filter action = customs_reopened.

Reopen count visibility

The declaration's detail page shows "Reopened N times" when reopen_count > 0. On the Customs list, a small badge flags repeat-reopens.

Repeated reopens on one declaration is a signal that something is structurally wrong — either the data is being entered incorrectly repeatedly, or the customs broker is making mistakes. Investigate.

Common pitfalls

Reporting

• Reopens This Quarter — count by broker, commodity, declaration type.
• Top-Reopened Declarations — the declarations with reopen_count >= 2. Review these individually for systemic issues.

Both under Forwarding → Reports → Customs.