Docs | EntryGo

Current contract direction:

POST /api/customs/optimize

Related protocol actions:

POST /api/exports/plan
POST /api/exports/execute
GET /api/exports/{id}

Status:

draft contract
preview response shape
production optimizer engine not yet enabled through this route

#Purpose

Use Customs Optimizer to normalize product customs inputs, propose HS classifications, surface compliance signals, and produce a merge report before planning.

This primitive is designed to become a metered AI surface inside EntryGo.

#Request body

Field	Type	Required	Description
`product_name`	string	yes	Product name used for optimization
`description`	string	yes	Human-readable product description
`country_of_origin`	string	yes	Two-letter country code
`value`	number	yes	Declared product value
`materials`	array of strings	no	Material list used for classification signals
`category`	string	no	Product category hint
`existing_hs_code`	string	no	Existing HS / HTS code to retain or review
`supplier_metadata`	object	no	Supplier-provided customs metadata
`account_id`	string	no	Account scope for future authenticated usage
`tenant_context`	object	no	Tenant-aware execution context

#JSON request example

json

{
  "product_name": "Cotton T-Shirt",
  "description": "Men's cotton t-shirt",
  "country_of_origin": "CN",
  "value": 35,
  "materials": ["cotton"],
  "category": "apparel"
}

#Success response

Important fields:

Field	Description
`optimizer_run_id`	Billable optimizer run identifier
`optimizer_attempt_id`	Specific optimizer attempt
`hs_code`	Proposed primary HS code
`candidate_classifications`	Alternative classifications with support scores
`confidence_score`	Numeric confidence score from `0` to `1`
`confidence_level`	Low / medium / high confidence band
`confidence_reasoning_summary`	Short explanation for confidence
`recommended_action`	Suggested next action
`compliance_flags`	Structured compliance signals
`merge_report`	Field normalization and missing-data summary
`attempt_number`	Attempt number for this run
`max_attempts`	Maximum attempts available
`retry_available`	Whether another attempt can be run
`retry_reason`	Why a retry is recommended or blocked
`metering`	Billable event counters for optimizer usage

#JSON response example

json

{
  "contract_status": "draft",
  "optimizer_run_id": "opt_run_demo_1001",
  "optimizer_attempt_id": "opt_attempt_demo_1",
  "hs_code": "6109.10",
  "candidate_classifications": [
    {
      "hs_code": "6109.10",
      "support_score": 0.87,
      "rationale_summary": "High confidence apparel match based on product name, description, and materials."
    }
  ],
  "confidence_score": 0.87,
  "confidence_level": "high",
  "confidence_reasoning_summary": "Structured product attributes strongly support a cotton apparel classification.",
  "recommended_action": "auto_accept",
  "compliance_flags": [],
  "merge_report": {
    "normalized_fields": ["product_name", "description", "country_of_origin", "value"],
    "missing_fields": [],
    "overrides_applied": [],
    "notes": ["Draft preview response for the Customs Optimizer contract."]
  },
  "retry_count": 0,
  "attempt_number": 1,
  "max_attempts": 3,
  "retry_available": true,
  "retry_reason": null,
  "signals": ["classification_ready", "planning_ready"],
  "notes": "Draft preview response. Production optimizer execution is not enabled in this route yet.",
  "metering": {
    "billable_event_type": "customs_optimization",
    "optimizer_run_count": 1,
    "optimizer_attempt_count": 1
  }
}

#Retry and confidence model

This draft contract exposes:

confidence_score
confidence_level
confidence_reasoning_summary
attempt_number
max_attempts
retry_available
retry_reason

These fields keep optimization outputs legible to both operators and automation systems.

#Future direction

Likely follow-on surfaces:

POST /api/customs/optimize/batch
GET /api/customs/optimizations/{id}

Those surfaces should preserve optimizer runs, attempts, merge reports, and metering events for large catalog and asynchronous workflows.