# Customs Clearance Webhook

*/Software/Customs_Clearance_Webhook*

## Solution Overview

The Customs Clearance Webhook accepts raw logistics documents—such as commercial invoices, packing lists, and bills of lading—via a standard REST endpoint and converts them into structured customs declaration payloads. It extracts line-item details, assigns Harmonized System (HS) codes based on product descriptions, and calculates estimated duties and taxes for cross-border shipments. The output is a standardized JSON object mapped to the specific entry requirements of the target country customs authority.

Digital freight forwarders and cross-border e-commerce platforms integrate this API to replace manual data entry in their international shipping workflows. Instead of employing teams of customs brokers to read PDFs and manually key data into legacy government portals, logistics providers route shipment documents directly to the webhook. It resolves the bottleneck of translating varied supplier invoices into the rigid data schemas demanded by border control agencies.

Operating as a Headless SaaS primitive, the webhook consumes raw document parsing APIs and global tariff databases from below to build its structured declarations. It is consumed from above by supply chain automation agents or custom ERP dashboards that orchestrate the broader freight lifecycle. Because customs declarations carry strict legal liabilities and fines for misclassification, the webhook routes routine payloads to automated filing endpoints but queues edge-case classifications into a dashboard for final review by a licensed human customs broker.

## Headless Saas Data Model

**Entities**:
- Name: CustomsDeclaration · Description: Structured customs declaration payload derived from logistics documents
- Name: Workspace · Description: Tenant account for digital freight forwarders and logistics providers
- Name: LogisticsDocument · Description: Raw input file such as commercial invoice or bill of lading
- Name: DeclarationLineItem · Description: Extracted item details including HS code and product description
- Name: FilingEvent · Description: Submission log to border control agencies or manual review queues
**Relations**:
- To: Workspace · From: CustomsDeclaration · Label: belongs to workspace · Cardinality: one-to-many
- To: CustomsDeclaration · From: LogisticsDocument · Label: provides data for · Cardinality: one-to-many
- To: CustomsDeclaration · From: DeclarationLineItem · Label: details shipment for · Cardinality: one-to-many
- To: CustomsDeclaration · From: FilingEvent · Label: records submission for · Cardinality: one-to-many
**Tenant Anchor**: Workspace
**Primary Resource**: CustomsDeclaration

## Api Definition

**Protocols**:
- REST
- MCP
- Webhooks
- SDK
**Consumed By**:
- [Freight Forwarding Agent](/Agents/Freight_Forwarding_Agent)
- [Cross-Border Shipping Agent](/Agents/Cross-Border_Shipping_Agent)
- [Logistics Triage Agent](/Agents/Logistics_Triage_Agent)
**Integrations**:
- [Google Document AI](/Products/Google_Document_AI)
- [CBP ACE](/Products/CBP_ACE)
- [Descartes Datamyne](/Products/Descartes_Datamyne)
- [WCO Trade Tools](/Products/WCO_Trade_Tools)
**Consumption Model**: A supply chain automation agent registers the MCP server, posts raw commercial invoices via REST to initiate processing, and listens to the clearance.updated webhook to track filing events.
**Workflow Wrappers**:
- Name: Process Logistics Documents · Wraps: accepts raw PDFs, extracts line items, assigns HS codes, and calculates estimated duties
- Name: File Customs Declaration · Wraps: formats the structured payload for target country requirements and submits to border agency endpoints
- Name: Queue Broker Review · Wraps: flags ambiguous classifications and pushes the declaration to a dashboard for licensed broker resolution

## Api Function Cascade

**Ai Role**: The primitive employs generative extraction and agentic classification loops to process customs documentation straight-through, executing deterministically and routing payloads to a human broker only when classification confidence fails to meet mandated thresholds.
**Cascade**:
- Kind: Code · Note: Accepts raw commercial invoices and shipping documents via REST POST. · Step: Ingest Logistics Payload · Verb: ingest · Realizes: Receive Shipment Data · Oversight: none
- Kind: Generative · Note: Uses Google Document AI to parse unstructured PDFs into structured line items. · Step: Extract Invoice Data · Verb: extract · Realizes: Extract Document Data · Oversight: none
- Kind: Agentic · Note: Iteratively queries Descartes Datamyne and WCO Trade Tools to map extracted line items. · Step: Assign Harmonized System Codes · Verb: classify · Realizes: Classify Trade Goods · Oversight: none
- Kind: Code · Note: Applies destination country logic to calculate precise financial obligations. · Step: Calculate Estimated Duties · Verb: calculate · Realizes: Calculate Tariffs And Duties · Oversight: none
- Kind: Code · Note: Flags low-confidence classifications and routes them to a dashboard for licensed broker resolution. · Step: Gate Ambiguous Classifications · Verb: route · Realizes: Review Customs Declarations · Oversight: review-on-exception
- Kind: Code · Note: Transforms the structured payload to meet target requirements and transmits to CBP ACE. · Step: Submit Border Declaration · Verb: submit · Realizes: File Customs Documentation · Oversight: none
- Kind: Code · Note: Emits clearance.updated events to subscribing freight and logistics agents. · Step: Broadcast Clearance Webhook · Verb: broadcast · Realizes: Notify Supply Chain Stakeholders · Oversight: none
**Optimizes**:
- [First-Pass Clearance Rate](/Metrics/First-Pass_Clearance_Rate)
- [HS Classification Accuracy](/Metrics/HS_Classification_Accuracy)
- [Declaration Cycle Time](/Metrics/Declaration_Cycle_Time)

## Headless Saas Representative Offer

**Warranty**: Maintains 99.9% API endpoint availability and guarantees adherence to current border agency payload formatting requirements, issuing service credits for unnotified downtime or ingestion failures.
**Price Band**: ~$0.50 to $2.50 per processed document or submitted customs declaration, depending on target jurisdiction and exception routing volume
**Pricing Kind**: UsageMeter
**Deliverables**:
- REST API and MCP server access for raw commercial invoice ingestion
- Structured data payloads containing extracted line items, assigned HS codes, and duty estimates
- Automated electronic filing transmissions to border agency endpoints
- Webhook notifications for clearance status updates and border holds
- Automated exception routing to human broker queues for ambiguous classifications
**Delivery Mode**: Self-serve API access where the consuming software provisions credentials and is metered instantaneously based on the volume of documents processed and declarations filed.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: API Key
**Endpoints**:
- GET /customs-declarations — list customs declarations
- POST /customs-declarations — create a customs declaration
- GET /customs-declarations/{id} — fetch a customs declaration
- PATCH /customs-declarations/{id} — update a customs declaration
- POST /customs-declarations/{id}/submit — submit the declaration to a customs agency
- GET /workspaces — list workspaces
- POST /workspaces — create a workspace
- GET /workspaces/{id} — fetch a workspace
- PATCH /workspaces/{id} — update a workspace
- GET /customs-declarations/{customsDeclarationId}/logistics-documents — list logistics documents for a declaration
- POST /customs-declarations/{customsDeclarationId}/logistics-documents — upload a logistics document
- GET /logistics-documents/{id} — fetch a logistics document
- PATCH /logistics-documents/{id} — update extracted document data
- GET /customs-declarations/{customsDeclarationId}/declaration-line-items — list line items for a declaration
- POST /customs-declarations/{customsDeclarationId}/declaration-line-items — add a line item to a declaration
- GET /declaration-line-items/{id} — fetch a declaration line item
- PATCH /declaration-line-items/{id} — update a declaration line item
- GET /customs-declarations/{customsDeclarationId}/filing-events — list filing events for a declaration
- POST /customs-declarations/{customsDeclarationId}/filing-events — record a filing event for a declaration
- GET /filing-events/{id} — fetch a filing event
**Multitenancy**: Row-level isolation
**Webhook Events**:
- customs_declaration.cleared
- customs_declaration.rejected
- logistics_document.extracted
- filing_event.recorded

## Headless Saas Erd

```mermaid
erDiagram
    CustomsDeclaration }o--|| Workspace : "belongs to workspace"
    LogisticsDocument }o--|| CustomsDeclaration : "provides data for"
    DeclarationLineItem }o--|| CustomsDeclaration : "details shipment for"
    FilingEvent }o--|| CustomsDeclaration : "records submission for"

    CustomsDeclaration {
        UUID id PK
        UUID workspaceId FK
        VARCHAR targetCountry
        VARCHAR clearanceStatus
        DECIMAL totalValue
        DECIMAL estimatedDuties
    }
    Workspace {
        UUID id PK "Tenant Key"
        VARCHAR name
        VARCHAR apiToken
        TIMESTAMP createdAt
    }
    LogisticsDocument {
        UUID id PK
        UUID customsDeclarationId FK
        VARCHAR documentType
        VARCHAR fileUrl
        JSONB extractedData
    }
    DeclarationLineItem {
        UUID id PK
        UUID customsDeclarationId FK
        VARCHAR hsCode
        TEXT productDescription
        DECIMAL quantity
        DECIMAL dutyAmount
    }
    FilingEvent {
        UUID id PK
        UUID customsDeclarationId FK
        VARCHAR eventType
        JSONB agencyResponse
        TIMESTAMP recordedAt
    }
```

## Neighborhood

### Composed into

- [Dockside Cargo Inspection Agent](/Agents/Dockside_Cargo_Inspection_Agent) — composes · Agents

### What it uses

- [Google Cloud Document AI](/Products/Google_Cloud_Document_AI) — uses · Products
- [Descartes Datamyne](/Products/Descartes_Datamyne) — uses · Products
- [WCO Trade Tools](/Products/WCO_Trade_Tools) — uses · Products
- [CBP ACE](/Products/CBP_ACE) — uses · Products

### Optimizes

- [Declaration Cycle Time](/Metrics/Declaration_Cycle_Time) — optimizes · Metrics
- [First-Pass Clearance Rate](/Metrics/First-Pass_Clearance_Rate) — optimizes · Metrics
- [HS Classification Accuracy](/Metrics/HS_Classification_Accuracy) — optimizes · Metrics

### Who consumes this

- [Cross-Border Shipping Agent](/Agents/Cross-Border_Shipping_Agent) — consumed by · Agents
- [Freight Forwarding Agent](/Agents/Freight_Forwarding_Agent) — consumed by · Agents
- [Logistics Triage Agent](/Agents/Logistics_Triage_Agent) — consumed by · Agents

### Similar Agents

- [Gateway Extraction Worker](/Agents/Gateway_Extraction_Worker) — similar · Agents
- [Unstructured Ingestion Engine](/Agents/Unstructured_Ingestion_Engine) — similar · Agents

### Similar Software

- [Shipping Manifest API](/Software/Shipping_Manifest_API) — similar · Software
- [Semantic Data Parser](/Software/Semantic_Data_Parser) — similar · Software
- [Document Extraction Model](/Software/Document_Extraction_Model) — similar · Software

### Similar Startups

- [Kerforder](/Startups/Kerforder) — similar · Startups
- [Brokeragecase](/Startups/Brokeragecase) — similar · Startups
- [Clearancewing](/Startups/Clearancewing) — similar · Startups
- [Tradenetgate](/Startups/Tradenetgate) — similar · Startups
- [M](/Startups/M) — similar · Startups
- [Heavyport](/Startups/Heavyport) — similar · Startups
- [Arrivalquay](/Startups/Arrivalquay) — similar · Startups
- [Cargoharbor](/Startups/Cargoharbor) — similar · Startups
- [Trade Flow Agent](/Startups/Trade_Flow_Agent) — similar · Startups
- [Burdendock](/Startups/Burdendock) — similar · Startups
- [Motade](/Startups/Motade) — similar · Startups
- [Challengequay](/Startups/Challengequay) — similar · Startups
- [Xin](/Startups/Xin) — similar · Startups
- [Foliumquay](/Startups/Foliumquay) — similar · Startups

### Similar Markets

- [Example Four](/Markets/Example_Four) — similar · Markets