Customs Duty Calculator

Overview

Customs duty and tax calculation engine. Supports ad valorem, specific, compound, and mixed duty types. Configurable tariff schedules, preferential rates, and trade agreement lookups. REST API for integration with customs clearance systems.

Features

• Multi-duty-type calculation -- ad valorem (percentage of value), specific (per unit/weight), compound (combination of both), and mixed duties
• FTA preferential rates -- automatic detection and application of Free Trade Agreement preferential tariff rates based on origin-destination pairs
• HS code tariff lookup -- hierarchical tariff schedule lookup supporting chapter, heading, and subheading levels
• Currency conversion -- configurable exchange rates for multi-currency duty calculations
• Batch processing -- calculate duties for multiple declaration line items in a single request

API Endpoints

Method	Endpoint	Description
POST	/calculate	Calculate duty for a single declaration
POST	/calculate/batch	Calculate duties for multiple declarations
GET	/tariff/{hsCode}	Look up tariff rate by HS code
GET	/health	Service health check

Example Request

POST /calculate
{
  "hsCode": "0901.11.00",
  "customsValue": 50000.00,
  "weight": 1000.0,
  "quantity": 1,
  "originCountry": "VN",
  "destinationCountry": "US",
  "currency": "USD"
}

Example Response

{
  "hsCode": "0901.11.00",
  "dutyType": "AdValorem",
  "dutyRate": 0.0,
  "dutyAmount": 0.00,
  "vatRate": 0.0,
  "vatAmount": 0.00,
  "totalAmount": 0.00,
  "currency": "USD",
  "preferentialRateApplied": true,
  "ftaName": "USVN-BTA",
  "breakdown": []
}

Build & Run

Prerequisites

• .NET 8 SDK

Using the Makefile

make build      # Build the solution
make test       # Run all tests
make run        # Run the API (listens on http://localhost:5000)
make clean      # Clean build artifacts

Using the .NET CLI

# Restore and build
dotnet build DutyCalculator.sln

# Run tests
dotnet test DutyCalculator.sln

# Run the API
dotnet run --project src/DutyCalculator/DutyCalculator.csproj

Using Docker

docker build -t customs-duty-calculator .
docker run -p 5000:8080 customs-duty-calculator

Project Structure

.
├── src/
│   └── DutyCalculator/
│       ├── Endpoints/          # REST API endpoint definitions
│       ├── Models/             # Domain models
│       ├── Services/           # Core business logic
│       ├── Program.cs          # Application entry point
│       └── DutyCalculator.csproj
├── tests/
│   └── DutyCalculator.Tests/  # Unit tests
├── config/
│   ├── tariff_schedule.json   # Sample tariff data
│   └── fta_agreements.json    # Sample FTA data
├── DutyCalculator.sln
├── Dockerfile
├── Makefile
└── LICENSE

Configuration

Tariff schedules and FTA agreements are loaded from JSON files in the config/ directory. These can be replaced with database-backed implementations for production use.

License

This project is licensed under the MIT License. See LICENSE for details.