{"openapi":"3.0.3","info":{"title":"Traddal API v1","version":"1.4.0","description":"## Introduction\n\nThe Traddal REST API framework enables you to quickly and easily integrate your software systems with customs duty calculations and order management for US, EU, and GB destinations.\n\n## Base URL\n\nThe **Base URL** is the initial part of an API request. All requests begin with this:\n\n**Production:** `https://api.traddal.com`\n\n## Authentication\n\nYou will need to provide a valid access token in every call you make to Traddal.\n\nAll requests require a **Bearer token** passed as an authorization header:\n```\nAuthorization: Bearer your-access-token-here\n```\n\nTo get your access token, use the OAuth2 client credentials flow with your API credentials.\n\n## Core Features\n\n### HS Classification\n- AI-powered product classification using vector search and LLM reranking\n- Classify products to HS/HTS codes for US, CA, EU, GB, and global nomenclature\n- Single and bulk classification endpoints with deduplication and caching\n- Structured results with confidence scores and AI reasoning\n\n### Duty Calculations\n- Calculate customs duties, taxes, and fees for international shipments\n- Support for US, EU, and GB destinations\n- Real-time exchange rates and tariff data\n- **Multiple Code Calculations**: Process multiple HS codes in a single request with reference tracking\n\n### Order Management\n- **Comprehensive Order Creation**: Create detailed orders with total value, estimated duties, optional shipping and insurance costs\n- **Multi-Currency Support**: Handle different currencies at order and item levels\n- **Flexible Decimal Amounts**: Accept precise decimal values for all monetary fields\n- **Multiple Items per Order**: Each item includes SKU, quantity, amount, HS code, and country of origin\n- **Complete Address Management**: Full sender and receiver information with contact details\n- **Order Status Tracking**: Monitor order progress and payment processing\n\n### Webhooks\nTraddal sends webhook events to notify your application when events occur. When an event is triggered, Traddal sends a POST request to your configured webhook URL with a JSON payload containing event details. All webhook requests include an `X-Traddal-Signature` header with an HMAC SHA-256 signature for verification.\n","contact":{"name":"Traddal API Support","url":"https://traddal.com","email":"support@traddal.com"}},"servers":[{"url":"https://api.traddal.com","description":"Production server"},{"url":"http://localhost:5002","description":"Development server"}],"tags":[{"name":"Authentication","description":"OAuth authentication endpoints for obtaining access tokens"},{"name":"Classification","description":"AI-powered product classification"},{"name":"Duty Calculation","description":"Calculate customs duties, taxes, and fees for international shipments"},{"name":"Orders","description":"Create and manage orders with items for duty collection"},{"name":"Webhooks","description":"Webhook event payloads sent to your configured endpoints"},{"name":"API Information","description":"General API information and health endpoints"}],"paths":{"/health":{"get":{"tags":["API Information"],"summary":"Health Check","description":"Check if the API service is running","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"Traddal API"}}}}}}}}},"/oauth/token":{"post":{"tags":["Authentication"],"summary":"Get Access Token","description":"Obtain an access token using OAuth2 client credentials flow","operationId":"getAccessToken","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"description":"OAuth2 grant type"},"client_id":{"type":"string","description":"Your API client ID"},"client_secret":{"type":"string","format":"password","description":"Your API client secret"}}}}}},"responses":{"200":{"description":"Token generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"JWT access token"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":3600}}}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/duties/calculate":{"post":{"tags":["Duty Calculation"],"summary":"Calculate Duties","description":"**Enhanced duty calculation with comprehensive fee calculations from database.**\n\n**Key Features:**\n- Database-driven fees (MPF, HMF, Cotton fees, etc.) with exact HS code matching\n- Weight-based fee calculations with automatic unit conversions\n- Preferential duty rates where available\n- Real-time currency conversions\n\n**MANDATORY FIELDS:**\n- `hs_code`: 10-digit HTS/HS code\n- `origin_country`: 2-letter origin country code\n- `destination_country`: 2-letter destination country code\n- `declared_value`: Value in origin currency (must be > 0)\n\n**OPTIONAL FIELDS:**\n- `measurement`: Unified measurement object with `value` and `unit` - auto-detects weight vs volume based on unit\n- `quantity`: Quantity of items for per-item duties (default: 1)\n\n**ROUTING:**\n- `destination_country = \"US\"` → U.S. calculation\n- `destination_country = \"GB\"` → UK calculation\n- `destination_country = EU countries` → EU calculation with VAT\n","operationId":"calculateDuties","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DutyCalculationRequest"},"examples":{"us_import":{"summary":"US Import - Apparel (weight-based)","value":{"hs_code":"6109100040","origin_country":"CN","destination_country":"US","declared_value":1000,"measurement":{"value":10.5,"unit":"kg"},"shipping_cost":50,"insurance_cost":10,"origin_country_currency":"CNY","quantity":1,"transport_mode":"sea"}},"eu_import":{"summary":"EU Import - Germany (weight-based)","value":{"hs_code":"61041320","origin_country":"CN","destination_country":"DE","declared_value":1000,"measurement":{"value":5.2,"unit":"kg"},"shipping_cost":100,"insurance_cost":50,"origin_country_currency":"CNY"}},"gb_import":{"summary":"GB Import (weight-based)","value":{"hs_code":"62041200","origin_country":"CN","destination_country":"GB","declared_value":800,"measurement":{"value":3,"unit":"kg"},"shipping_cost":75,"insurance_cost":25,"origin_country_currency":"CNY"}},"us_spirits_import":{"summary":"US Spirits Import - Tequila (proof liters)","description":"Spirits with specific duties calculated per proof liter","value":{"hs_code":"2208902000","origin_country":"MX","destination_country":"US","declared_value":500,"measurement":{"value":80,"unit":"proof_liters"},"quantity":12,"shipping_cost":100,"insurance_cost":20,"origin_country_currency":"USD","transport_mode":"sea"}},"us_wine_import":{"summary":"US Wine Import (liters)","description":"Wine with duties calculated per liter","value":{"hs_code":"2204210060","origin_country":"FR","destination_country":"US","declared_value":300,"measurement":{"value":9,"unit":"liter"},"quantity":12,"shipping_cost":75,"insurance_cost":15,"origin_country_currency":"EUR","transport_mode":"air"}},"us_oil_import":{"summary":"US Petroleum Import (barrels)","description":"Petroleum products with duties per barrel","value":{"hs_code":"2709000000","origin_country":"SA","destination_country":"US","declared_value":50000,"measurement":{"value":100,"unit":"bbl"},"shipping_cost":5000,"origin_country_currency":"USD","transport_mode":"sea"}},"us_diamonds_import":{"summary":"US Diamonds Import (carats)","description":"Gemstones with weight in carats","value":{"hs_code":"7102310000","origin_country":"BE","destination_country":"US","declared_value":25000,"measurement":{"value":5,"unit":"carat"},"quantity":1,"shipping_cost":100,"insurance_cost":500,"origin_country_currency":"EUR","transport_mode":"air"}},"us_lumber_import":{"summary":"US Lumber Import (cubic meters)","description":"Wood products with volume in cubic meters","value":{"hs_code":"4407110000","origin_country":"CA","destination_country":"US","declared_value":15000,"measurement":{"value":50,"unit":"m3"},"shipping_cost":2000,"origin_country_currency":"CAD","transport_mode":"sea"}},"us_steel_import":{"summary":"US Steel Import (metric tons)","description":"Steel products with weight in metric tons","value":{"hs_code":"7208510000","origin_country":"KR","destination_country":"US","declared_value":100000,"measurement":{"value":25,"unit":"t"},"shipping_cost":5000,"origin_country_currency":"USD","transport_mode":"sea"}},"us_derivative_steel":{"summary":"US Derivative Product - Steel Component (Section 232)","description":"Product containing steel from a Section 232 country","value":{"hs_code":"8708999890","origin_country":"MX","destination_country":"US","declared_value":500,"measurement":{"value":10,"unit":"kg"},"components":[{"type":"frame","material":"steel","percentage":25,"origin_country":"CN"}],"origin_country_currency":"USD"}},"us_timepiece_import":{"summary":"US Timepiece Import - Watch with Swiss Movement","description":"Watch with automatic movement and jewels","value":{"hs_code":"9102110000","origin_country":"HK","destination_country":"US","declared_value":250,"quantity":1,"components":[{"type":"movement","mechanism":"automatic","jewels":21,"origin_country":"CH"},{"type":"case","material":"steel","origin_country":"HK"},{"type":"band","material":"leather","origin_country":"IT"}],"origin_country_currency":"USD"}}}}}},"responses":{"200":{"description":"Successful calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DutyCalculationResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/duties/calculate/multiple":{"post":{"tags":["Duty Calculation"],"summary":"Calculate Multiple Duties","description":"Calculate customs duties for multiple HS codes in a single request.\n\n**Common Fields**: Apply to all codes in the request:\n- `destination_country`: Where all goods are being imported to\n- `shipping_cost`: Total shipping cost distributed across all codes\n- `transport_mode`: Mode of transport for all items\n- `weight` and `weight_unit`: Optional default values if not specified per item\n\n**Individual Code Fields**: Each code in the `codes` array must include:\n- `hs_code`: The HS/HTS harmonized system code\n- `origin_country`: 2-letter origin country code\n- `declared_value`: Value in origin currency\n- `weight`: Weight for this specific item (required for accurate fee calculation)\n- `weight_unit`: Weight unit for this item\n- `origin_country_currency`: Optional currency code\n","operationId":"calculateMultipleDuties","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiDutyCalculationRequest"},"examples":{"multi_us_import":{"summary":"Multiple US Import Example","value":{"reference":"order-123","destination_country":"US","destination_country_currency":"USD","shipping_cost":200,"insurance_cost":50,"transport_mode":"sea","codes":[{"hs_code":"6109100040","origin_country":"CN","declared_value":1000,"origin_country_currency":"CNY","weight":10,"weight_unit":"kg"},{"hs_code":"6204620090","origin_country":"BD","declared_value":800,"origin_country_currency":"USD","weight":5,"weight_unit":"kg"}]}},"multi_alcohol_import":{"summary":"Multiple Alcohol Import - Spirits with Proof Liters","description":"Example showing mixed alcohol products with volume-based specific duties","value":{"reference":"spirits-order-456","destination_country":"US","destination_country_currency":"USD","shipping_cost":150,"insurance_cost":30,"transport_mode":"sea","codes":[{"hs_code":"2208902000","origin_country":"MX","declared_value":600,"origin_country_currency":"USD","weight":14,"weight_unit":"kg","volume":80,"volume_unit":"proof_liter"},{"hs_code":"2204210060","origin_country":"FR","declared_value":400,"origin_country_currency":"EUR","weight":18,"weight_unit":"kg","volume":12,"volume_unit":"liter"}]}}}}}},"responses":{"200":{"description":"Successful batch calculation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"request_id":{"type":"string","format":"uuid","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"},"reference":{"type":"string","example":"order-123"},"calculation_type":{"type":"string","example":"US"},"destination_country":{"type":"string","example":"US"},"transport_mode":{"type":"string","example":"air"},"shipping_terms":{"type":"string","example":"FOB"},"quantity":{"type":"number","example":1},"values":{"type":"object","properties":{"shipping_cost":{"type":"number","example":200},"insurance_cost":{"type":"number","example":50}}},"currencies":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"exchange_rate":{"type":"number"},"exchange_rate_display":{"type":"string"}}},"exemptions":{"type":"object","properties":{"de_minimis_threshold":{"type":"number"},"de_minimis_exempt":{"type":"boolean"}}},"results":{"type":"array","description":"Array of calculation results for each HS code","items":{"oneOf":[{"type":"object","description":"Successful calculation result","properties":{"hs_code":{"type":"string","example":"6207110000"},"origin_country":{"type":"string","example":"CN"},"weight":{"type":"number","description":"Weight of this item (if provided)","example":1},"weight_unit":{"type":"string","description":"Weight unit (if weight is provided)","example":"kg"},"volume":{"type":"number","description":"Volume of this item (if provided for volume-based duties)","example":9},"volume_unit":{"type":"string","description":"Volume unit (if volume is provided)","example":"liter"},"declared_value":{"type":"number","example":100},"origin_country_currency":{"type":"string","example":"USD"},"estimated_duties":{"type":"object","properties":{"normal_tariff":{"type":"object","properties":{"tariffs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rate":{"type":"string"},"amount":{"type":"number"},"type":{"type":"string"}}}},"total_duty":{"type":"number"}}},"preferential_tariff":{"type":"object","nullable":true,"properties":{"tariffs":{"type":"array","items":{"type":"object"}},"total_duty":{"type":"number"}}},"total_duty":{"type":"number"}}},"fees":{"type":"object","properties":{"MPF":{"type":"object","properties":{"code":{"type":"string"},"amount":{"type":"number"}}},"Cotton Fee":{"type":"object","properties":{"code":{"type":"string"},"amount":{"type":"number"}}},"total_fees":{"type":"number"}}},"additional_tariff_measures":{"type":"array","description":"Additional regulatory requirements for this HS code","items":{"type":"object","properties":{"code":{"type":"string","example":"FDA"},"name":{"type":"string","example":"FDA - May Be Regulated"},"description":{"type":"string"},"agency":{"type":"string","example":"Food and Drug Administration (FDA)"},"measure_type":{"type":"string","example":"Health / Safety"},"condition":{"type":"string","nullable":true}}}}}},{"type":"object","description":"Failed calculation result","properties":{"hs_code":{"type":"string","example":"1111"},"error":{"type":"string","example":"HS code '1111' not found in US tariff database"}}}]}}}}}}}}}},"/v1/classify":{"post":{"tags":["Classification"],"summary":"Classify Product","description":"Classify a product description to an HS/HTS code using AI-powered classification.\n\n**Supported Countries:** `US`, `CA`, `EU`, `GB`, `GLOBAL`\n\n**Classification Modes (`mode`):**\n- `mini` — fastest mode\n- `pro` — balanced/default mode\n- `max` — highest-accuracy mode\n","operationId":"classifyProduct","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyRequest"},"examples":{"apparel":{"summary":"Classify apparel product","value":{"description":"men's cotton t-shirt","destination_country":"us","mode":"pro"}},"mini_fast":{"summary":"Fast classification mode (mini)","value":{"description":"adidas size 12 sneakers","destination_country":"us","mode":"mini"}},"max_accuracy":{"summary":"Highest-accuracy mode (max)","value":{"description":"stainless steel insulated water bottle with lid","destination_country":"us","mode":"max"}},"electronics":{"summary":"Classify electronics product","value":{"description":"wireless bluetooth headphones","destination_country":"us"}},"with_hs_code":{"summary":"Classify with HS code hint","value":{"description":"cotton doll for children","destination_country":"us","hs_code":"9503"}},"hts_lookup":{"summary":"Direct HTS code lookup","value":{"description":"9504.90.6000","destination_country":"us"}}}}}},"responses":{"200":{"description":"Successful classification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyResponse"}}}},"400":{"description":"Invalid request (missing description or unsupported country)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyError"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyError"}}}}}}},"/v1/classify/bulk":{"post":{"tags":["Classification"],"summary":"Bulk Classify Products","description":"Classify multiple product descriptions in a single request with optimized batch processing.\n\n**Optimizations:**\n- **Deduplication**: Identical descriptions for the same country are classified once\n- **Batch normalization**: All descriptions are normalized in a single LLM call\n- **Parallel processing**: Vector searches and reranking run in parallel\n- **Caching**: Results are cached to speed up repeated requests\n\n**Limits:** Maximum 50 items per request.\n\n**Supported Countries:** `US`, `CA`, `EU`, `GB`, `GLOBAL`\n","operationId":"bulkClassifyProducts","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkClassifyRequest"},"examples":{"mixed_products":{"summary":"Classify multiple products","value":{"items":[{"description":"men's cotton t-shirt","destination_country":"us"},{"description":"wireless bluetooth headphones","destination_country":"us"},{"description":"ceramic coffee mug","destination_country":"eu"}]}}}}}},"responses":{"200":{"description":"Successful bulk classification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkClassifyResponse"}}}},"400":{"description":"Invalid request (empty items, exceeds max batch size, or invalid item)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Maximum batch size is 50 items"},"execution_time":{"type":"integer","example":5}}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"},"details":{"type":"string"},"execution_time":{"type":"integer"}}}}}}}}},"/v1/orders":{"post":{"tags":["Orders"],"summary":"Create Order","description":"Create a new order for duty collection with comprehensive details including:\n- Order reference and total value (required)\n- **Automatic duty calculation** based on items' HS codes, origin countries, and destination\n- Optional transport mode (sea, air, road, rail) for accurate duty calculation\n- Optional shipping and insurance costs\n- Multiple items with SKU, quantity, amount, HS code, country of origin, weight, and weight unit\n- Complete sender and receiver information including company names and contact details\n- All monetary values support decimal precision\n- Multi-currency support at different levels\n\n**Duty Calculation:**\nDuties are automatically calculated from the items in your order. The response includes a `charges` object with:\n- `estimated_duties`: Estimated customs duties only\n- `fees`: Import fees (MPF, HMF, etc.)\n- `collection_fee`: Your collection fee (if configured)\n- `total`: Sum of all charges\n\n**Note:** Do not include `estimated_duties` in the request - it will be calculated automatically.\n","operationId":"createOrder","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"201":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/payment.succeeded":{"post":{"tags":["Webhooks"],"summary":"payment.succeeded","description":"Sent when a payment is successfully completed via Stripe.\n\n**Headers:**\n- `Content-Type: application/json`\n- `User-Agent: Traddal-Webhooks/1.0`\n- `X-Traddal-Event: payment.succeeded`\n- `X-Traddal-Signature: <hmac_sha256_signature>` (if webhook secret configured)\n","operationId":"webhookPaymentSucceeded","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload_PaymentSucceeded"}}}},"responses":{"200":{"description":"Webhook received successfully","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","example":true}}}}}}}}},"/webhooks/payment.failed":{"post":{"tags":["Webhooks"],"summary":"payment.failed","description":"Sent when a payment fails.\n\n**Headers:**\n- `Content-Type: application/json`\n- `User-Agent: Traddal-Webhooks/1.0`\n- `X-Traddal-Event: payment.failed`\n- `X-Traddal-Signature: <hmac_sha256_signature>` (if webhook secret configured)\n","operationId":"webhookPaymentFailed","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload_PaymentFailed"}}}},"responses":{"200":{"description":"Webhook received successfully","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","example":true}}}}}}}}},"/webhooks/order.created":{"post":{"tags":["Webhooks"],"summary":"order.created","description":"Sent when a new order is created.\n\n**Headers:**\n- `Content-Type: application/json`\n- `User-Agent: Traddal-Webhooks/1.0`\n- `X-Traddal-Event: order.created`\n- `X-Traddal-Signature: <hmac_sha256_signature>` (if webhook secret configured)\n","operationId":"webhookOrderCreated","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload_OrderCreated"}}}},"responses":{"200":{"description":"Webhook received successfully","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","example":true}}}}}}}}},"/webhooks/order.updated":{"post":{"tags":["Webhooks"],"summary":"order.updated","description":"Sent when an order is updated.\n\n**Headers:**\n- `Content-Type: application/json`\n- `User-Agent: Traddal-Webhooks/1.0`\n- `X-Traddal-Event: order.updated`\n- `X-Traddal-Signature: <hmac_sha256_signature>` (if webhook secret configured)\n","operationId":"webhookOrderUpdated","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload_OrderUpdated"}}}},"responses":{"200":{"description":"Webhook received successfully","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","example":true}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DutyCalculationRequest":{"type":"object","required":["hs_code","origin_country","destination_country","declared_value"],"properties":{"hs_code":{"type":"string","description":"HS/HTS harmonized system code","example":"6109100040"},"origin_country":{"type":"string","description":"2-letter origin country code","minLength":2,"maxLength":2,"example":"CN"},"destination_country":{"type":"string","description":"2-letter destination country code","minLength":2,"maxLength":2,"example":"US"},"declared_value":{"type":"number","description":"Declared value in origin currency","minimum":0,"example":1000},"weight":{"type":"number","description":"Weight of goods (optional, but if provided, weight_unit is required for weight-based fee calculations)","minimum":0,"example":10.5},"weight_unit":{"type":"string","description":"Unit of weight (required if weight is provided)","enum":["kg","lb"],"example":"kg"},"volume":{"type":"number","description":"Volume of goods (required for volume-based specific duties like alcohol/spirits)","minimum":0,"example":9},"volume_unit":{"type":"string","description":"Unit of volume (required if volume is provided).\n- `liter` - Standard liters\n- `ml` - Milliliters (converted to liters)\n- `hl` - Hectoliters (converted to liters)\n- `gallon` - US gallons (converted to liters)\n- `proof_liter` - Proof liters for spirits (not converted, used directly for alcohol duty calculations)\n","enum":["liter","ml","hl","gallon","proof_liter"],"example":"liter"},"measurement":{"type":"object","description":"Unified measurement object - alternative to separate weight/volume fields.\nThe unit determines whether it's treated as weight or volume.\nWeight units: kg, kilogram, lb, lbs, pound, g, gram, oz, ounce, t, ton, tonne, carat\nVolume units: l, liter, litre, liters, ml, milliliter, gal, gallon, hl, hectoliter, proof_liters, bbl, barrel, m3\n","properties":{"value":{"type":"number","description":"The measurement value","minimum":0,"example":80},"unit":{"type":"string","description":"Unit of measurement. Auto-detected as weight or volume:\n- Weight: kg, kilogram, lb, lbs, pound, g, gram, oz, ounce, t, ton, tonne, carat\n- Volume: l, liter, litre, liters, ml, milliliter, gal, gallon, hl, hectoliter, proof_liters, bbl, barrel, m3\n","example":"proof_liters"}}},"shipping_cost":{"type":"number","description":"Shipping cost","minimum":0,"example":50},"insurance_cost":{"type":"number","description":"Insurance cost","minimum":0,"example":10},"origin_country_currency":{"type":"string","description":"3-letter currency code for origin","minLength":3,"maxLength":3,"example":"CNY"},"destination_country_currency":{"type":"string","description":"3-letter currency code for destination","minLength":3,"maxLength":3,"example":"USD"},"quantity":{"type":"integer","description":"Quantity of items. For count-based specific duties, you may need to adjust based on the unit of measure:\n- For per-item duties: provide actual count\n- For per-dozen duties: provide actual count (will be divided by 12)\n- For per-gross duties: provide actual count (will be divided by 144, as 1 gross = 12 dozen = 144 units)\n","minimum":1,"default":1},"transport_mode":{"type":"string","description":"Mode of transport","enum":["sea","air","road","rail"],"default":"sea"},"shipping_terms":{"type":"string","description":"Shipping terms","enum":["FOB","CIF","EXW","DDP"],"default":"FOB"},"entry_date":{"type":"string","format":"date","description":"Entry date for historical calculations"},"trade_agreement":{"type":"string","description":"Trade agreement or country group code to apply special tariff rates.\nWhen provided, the system will look for additional tariffs where `origin_area_id` matches this value.\nExamples: USMCA, GSP, CN_HK, ASEAN, EU\n","example":"USMCA"},"components":{"type":"array","description":"Product components for derivative products (Section 232 metals, timepieces, etc.).\nUse this to specify material content, origin, and characteristics of product components.\n","items":{"type":"object","properties":{"type":{"type":"string","description":"Component type (e.g., \"movement\", \"case\", \"band\", \"frame\")","example":"movement"},"material":{"type":"string","description":"Material type (e.g., \"steel\", \"aluminum\", \"gold\", \"brass\")","example":"steel"},"percentage":{"type":"number","description":"Percentage of product value (use this OR value, not both)","minimum":0,"maximum":100,"example":15},"value":{"type":"number","description":"Actual component value in origin currency (use this OR percentage, not both)","minimum":0,"example":50},"origin_country":{"type":"string","description":"2-letter country code where component originated","minLength":2,"maxLength":2,"example":"CN"},"mechanism":{"type":"string","description":"For timepieces - mechanism type (e.g., \"automatic\", \"quartz\", \"mechanical\")","example":"automatic"},"jewels":{"type":"integer","description":"For timepieces - number of jewels in movement","minimum":0,"example":21}}},"example":[{"type":"frame","material":"steel","percentage":25,"origin_country":"CN"},{"type":"movement","mechanism":"automatic","jewels":21,"origin_country":"CH"}]}}},"MultiDutyCalculationRequest":{"type":"object","required":["destination_country","codes"],"properties":{"reference":{"type":"string","description":"Reference identifier for the calculation batch","example":"order-123"},"destination_country":{"type":"string","description":"2-letter destination country code","minLength":2,"maxLength":2,"example":"US"},"destination_country_currency":{"type":"string","description":"3-letter currency code for destination","minLength":3,"maxLength":3,"example":"USD"},"weight":{"type":"number","description":"Default weight for items without specific weight (optional, but if provided, weight_unit is required)","minimum":0,"example":15},"weight_unit":{"type":"string","description":"Default weight unit (required if weight is provided)","enum":["kg","lb"],"example":"kg"},"volume":{"type":"number","description":"Default volume for items without specific volume (optional, for volume-based specific duties)","minimum":0,"example":10},"volume_unit":{"type":"string","description":"Default volume unit (required if volume is provided)","enum":["liter","ml","hl","gallon","proof_liter"],"example":"liter"},"quantity":{"type":"number","description":"Quantity applied to all codes","minimum":0,"default":1},"shipping_cost":{"type":"number","description":"Total shipping cost for all items","minimum":0,"example":200},"insurance_cost":{"type":"number","description":"Total insurance cost for all items","minimum":0,"example":50},"quantity_unit":{"type":"string","description":"Unit of quantity","example":"No."},"transport_mode":{"type":"string","description":"Mode of transport","enum":["sea","air","road","rail"],"default":"sea"},"shipping_terms":{"type":"string","description":"Shipping terms","enum":["FOB","CIF","EXW","DDP"],"default":"FOB"},"entry_date":{"type":"string","format":"date","description":"Entry date for historical calculations"},"codes":{"type":"array","description":"List of HS codes with their individual details","minItems":1,"items":{"type":"object","required":["hs_code","origin_country","declared_value"],"properties":{"hs_code":{"type":"string","description":"HS/HTS harmonized system code","example":"6109100040"},"origin_country":{"type":"string","description":"2-letter origin country code","minLength":2,"maxLength":2,"example":"CN"},"declared_value":{"type":"number","description":"Declared value in origin currency","minimum":0,"example":1000},"origin_country_currency":{"type":"string","description":"3-letter currency code for origin","minLength":3,"maxLength":3,"example":"CNY"},"weight":{"type":"number","description":"Weight for this specific item (optional, but if provided, weight_unit is required)","minimum":0,"example":5},"weight_unit":{"type":"string","description":"Weight unit for this specific item (required if weight is provided)","enum":["kg","lb"],"example":"kg"},"volume":{"type":"number","description":"Volume for this specific item (required for volume-based duties like alcohol)","minimum":0,"example":9},"volume_unit":{"type":"string","description":"Volume unit for this specific item (liter, ml, hl, gallon, proof_liter)","enum":["liter","ml","hl","gallon","proof_liter"],"example":"liter"}}}}}},"DutyCalculationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"request_id":{"type":"string","format":"uuid","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"},"calculation_type":{"type":"string","enum":["US","GB","EU"]},"hs_code":{"type":"string"},"origin_country":{"type":"string"},"destination_country":{"type":"string"},"transport_mode":{"type":"string","example":"air"},"shipping_terms":{"type":"string","example":"FOB"},"quantity":{"type":"number","example":1},"weight":{"type":"number","description":"Weight of goods (if provided)","example":10.5},"weight_unit":{"type":"string","description":"Unit of weight (if weight is provided)","example":"kg"},"volume":{"type":"number","description":"Volume of goods (if provided)","example":9},"volume_unit":{"type":"string","description":"Unit of volume (if volume is provided)","example":"liter"},"currencies":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"exchange_rate":{"type":"number"},"exchange_rate_display":{"type":"string"}}},"exemptions":{"type":"object","properties":{"de_minimis_threshold":{"type":"number"},"de_minimis_exempt":{"type":"boolean"}}},"values":{"type":"object","properties":{"declared_value":{"type":"number","description":"Declared value in USD","example":137.93},"cbp_value":{"type":"number","description":"CBP rounded value (per 19 CFR § 159.3 - amounts under $0.50 round down, $0.50+ round up)","example":138},"shipping_cost":{"type":"number","description":"Shipping cost in USD","example":6.9},"insurance_cost":{"type":"number","description":"Insurance cost in USD","example":1.38}}},"trade_agreement":{"type":"string","description":"Trade agreement code applied (if passed in request and country is a member)","example":"AU"},"estimated_duties":{"type":"object","description":"Duty calculation results. Structure depends on AUTOMATIC_PREF_RATE environment setting:\n- Default (AUTOMATIC_PREF_RATE=false): Flat structure with tariffs array directly\n- AUTOMATIC_PREF_RATE=true: Nested normal_tariff and preferential_tariff objects\n","properties":{"tariffs":{"type":"array","description":"Array of applicable tariffs (flat structure when AUTOMATIC_PREF_RATE=false)","items":{"type":"object","properties":{"name":{"type":"string","example":"Customs Duty"},"rate":{"type":"string","example":"16.5%"},"amount":{"type":"number","example":22.77},"type":{"type":"string","enum":["CUSTOMS_DUTY","SPECIFIC","ADDITIONAL","SECTION_301","SECTION_232","RECIPROCAL","IEEPA","FENTANYL"],"example":"CUSTOMS_DUTY"},"code":{"type":"string","description":"HS code the tariff applies to","example":"6109100040"},"agreement_name":{"type":"string","description":"Name of trade agreement (if preferential rate applied)","example":"Australia FTA"},"agreement_code":{"type":"string","description":"Code of trade agreement (if preferential rate applied)","example":"AU"}}}},"total_duty":{"type":"number","description":"Total duty amount","example":22.77},"agreement_name":{"type":"string","description":"Trade agreement name (when trade_agreement is passed and country is member)","example":"Australia FTA"},"agreement_code":{"type":"string","description":"Trade agreement code (when trade_agreement is passed and country is member)","example":"AU"},"note":{"type":"string","description":"Additional notes (e.g., for Column 2 countries)","example":"Column 2 rates apply to goods from Cuba, North Korea, Russia, and Belarus"},"normal_tariff":{"type":"object","nullable":true,"description":"General Rate of Duty (only when AUTOMATIC_PREF_RATE=true)","properties":{"tariffs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Customs Duty"},"rate":{"type":"string","example":"16.5%"},"amount":{"type":"number","example":22.77},"type":{"type":"string","enum":["CUSTOMS_DUTY","SPECIFIC","ADDITIONAL"],"example":"CUSTOMS_DUTY"}}}},"total_duty":{"type":"number","description":"Total normal tariff duty","example":22.77}}},"preferential_tariff":{"type":"object","nullable":true,"description":"Special/Preferential Rate of Duty (only when AUTOMATIC_PREF_RATE=true)","properties":{"tariffs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Customs Duty (Preferential)"},"rate":{"type":"string","example":"0%"},"amount":{"type":"number","example":0},"type":{"type":"string","enum":["PREFERENTIAL_DUTY","SPECIFIC","ADDITIONAL"],"example":"PREFERENTIAL_DUTY"}}}},"total_duty":{"type":"number","description":"Total preferential tariff duty","example":0},"agreement_name":{"type":"string","description":"Name of trade agreement","example":"Australia FTA"},"agreement_code":{"type":"string","description":"Code of trade agreement","example":"AU"}}}}},"fees":{"type":"object","description":"Database-driven fees structure with codes and amounts","properties":{"MPF":{"type":"object","properties":{"code":{"type":"string","example":"499"},"amount":{"type":"number","example":25}}},"HMF":{"type":"object","properties":{"code":{"type":"string","example":"400"},"amount":{"type":"number","example":12.5}}},"Cotton":{"type":"object","properties":{"code":{"type":"string","example":"462"},"amount":{"type":"number","example":1.327}}},"total_fees":{"type":"number","description":"Sum of all applicable fees","example":38.827}}},"additional_tariff_measures":{"type":"array","description":"Additional regulatory requirements (e.g., PGA flags for US imports)","items":{"type":"object","properties":{"code":{"type":"string","description":"Additional measure code","example":"FDA"},"name":{"type":"string","description":"Short name of the requirement","example":"FDA - May Be Regulated"},"description":{"type":"string","description":"Full description of the requirement","example":"Product may or may not be FDA-regulated; if regulated, transmit FDA entry data; otherwise disclaim."},"agency":{"type":"string","description":"Responsible government agency","example":"Food and Drug Administration (FDA)"},"measure_type":{"type":"string","description":"Type of measure","example":"Health / Safety"},"condition":{"type":"string","nullable":true,"description":"Optional condition or notes specific to this HS code","example":null}}}},"vat":{"type":"object","description":"VAT information (EU and GB only)","properties":{"rate":{"type":"number","description":"VAT rate as percentage","example":20},"amount":{"type":"number","description":"VAT amount in destination currency","example":240},"exempt":{"type":"boolean","description":"Whether VAT exemption applies","example":false}}},"totals":{"type":"object","properties":{"total_duties_vat":{"type":"number","description":"Total duties and VAT","example":405},"total_landed_cost":{"type":"number","description":"Total landed cost including all duties, taxes, and fees","example":1443.827}}}}},"CreateOrderRequest":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["ref","value","items","sender","receiver"],"properties":{"ref":{"type":"string","description":"Order reference","example":"ORD-2024-001"},"value":{"type":"object","properties":{"amount":{"type":"number","minimum":0},"currency_code":{"type":"string","minLength":3,"maxLength":3}}},"estimated_duties":{"type":"object","description":"DEPRECATED - Use automatic duty calculation instead. This field is no longer used in order creation.","deprecated":true,"properties":{"amount":{"type":"number","minimum":0},"currency_code":{"type":"string","minLength":3,"maxLength":3}}},"shipping":{"type":"object","properties":{"amount":{"type":"number","minimum":0},"currency_code":{"type":"string","minLength":3,"maxLength":3}}},"insurance":{"type":"object","properties":{"amount":{"type":"number","minimum":0},"currency_code":{"type":"string","minLength":3,"maxLength":3}}},"transport_mode":{"type":"string","description":"Mode of transport (used for duty calculation)","enum":["sea","air","road","rail"],"example":"air"},"carrier_tracking":{"type":"object","description":"Optional carrier tracking information","properties":{"name":{"type":"string","description":"Carrier name","example":"DHL"},"code":{"type":"string","description":"Tracking code","example":"1234567890"},"url":{"type":"string","description":"Tracking URL","example":"https://www.dhl.com/track?code=1234567890"}}},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["sku","quantity","amount","currency_code","hs_code","country_of_origin_code"],"properties":{"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1},"amount":{"type":"number","minimum":0},"currency_code":{"type":"string","minLength":3,"maxLength":3},"hs_code":{"type":"string"},"country_of_origin_code":{"type":"string","minLength":2,"maxLength":2},"weight":{"type":"number","description":"Weight of this item (required if weight_unit is provided)","minimum":0},"weight_unit":{"type":"string","description":"Weight unit (required if weight is provided)","enum":["kg","lb"]},"url":{"type":"string","description":"URL for the item (product page, image, etc.)","example":"https://example.com/products/widget-001"}}}},"sender":{"$ref":"#/components/schemas/SenderInfo"},"receiver":{"$ref":"#/components/schemas/ReceiverInfo"}}}}},"SenderInfo":{"type":"object","required":["address_1","town","postcode","country_code","contact"],"properties":{"company_name":{"type":"string"},"address_1":{"type":"string"},"address_2":{"type":"string"},"address_3":{"type":"string"},"town":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"},"country_code":{"type":"string","minLength":2,"maxLength":2},"contact":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"taxes":{"type":"object","description":"Tax identification numbers for sender","properties":{"tax_id_number":{"type":"string","description":"General tax identification number","example":"123456789"},"ioss_number":{"type":"string","description":"Import One-Stop Shop number (EU)","example":"IM1234567890"},"vat_number":{"type":"string","description":"VAT registration number","example":"GB123456789"},"eori_number":{"type":"string","description":"Economic Operators Registration and Identification number","example":"GB123456789000"}}}}},"ReceiverInfo":{"type":"object","required":["address_1","town","postcode","country_code","contact"],"properties":{"company_name":{"type":"string"},"address_1":{"type":"string"},"address_2":{"type":"string"},"address_3":{"type":"string"},"town":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"},"country_code":{"type":"string","minLength":2,"maxLength":2},"contact":{"type":"object","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"taxes":{"type":"object","description":"Tax identification numbers for receiver","properties":{"tax_id_number":{"type":"string","description":"General tax identification number","example":"987654321"},"ioss_number":{"type":"string","description":"Import One-Stop Shop number (EU)","example":"IM0987654321"},"vat_number":{"type":"string","description":"VAT registration number","example":"US987654321"},"eori_number":{"type":"string","description":"Economic Operators Registration and Identification number","example":"US987654321000"}}}}},"OrderResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"request_id":{"type":"string","format":"uuid","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"ref":{"type":"string","example":"ORD-2024-001"},"value":{"type":"object","properties":{"amount":{"type":"number","example":1000},"currency_code":{"type":"string","example":"USD"}}},"charges":{"type":"object","nullable":true,"description":"Breakdown of all charges (estimated duties, fees, and collection fee)","properties":{"estimated_duties":{"type":"object","description":"Estimated customs duties only","properties":{"amount":{"type":"number","example":120},"currency_code":{"type":"string","example":"USD"}}},"fees":{"type":"object","description":"Import fees (MPF, HMF, etc.)","properties":{"amount":{"type":"number","example":30},"currency_code":{"type":"string","example":"USD"}}},"collection_fee":{"type":"object","description":"Collection fee (if applicable)","properties":{"amount":{"type":"number","example":15},"currency_code":{"type":"string","example":"USD"}}},"total":{"type":"object","description":"Total of all charges (estimated_duties + fees + collection_fee)","properties":{"amount":{"type":"number","example":165},"currency_code":{"type":"string","example":"USD"}}}}},"shipping":{"type":"object","nullable":true,"properties":{"amount":{"type":"number","example":50},"currency_code":{"type":"string","example":"USD"}}},"insurance":{"type":"object","nullable":true,"properties":{"amount":{"type":"number","example":25},"currency_code":{"type":"string","example":"USD"}}},"transport_mode":{"type":"string","nullable":true,"description":"Mode of transport","enum":["sea","air","road","rail"],"example":"air"},"carrier":{"type":"string","nullable":true,"description":"Carrier name","example":"DHL"},"carrier_tracking_code":{"type":"string","nullable":true,"description":"Tracking code","example":"1234567890"},"carrier_tracking_url":{"type":"string","nullable":true,"description":"Tracking URL","example":"https://www.dhl.com/track?code=1234567890"},"sender":{"$ref":"#/components/schemas/SenderInfo"},"receiver":{"$ref":"#/components/schemas/ReceiverInfo"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"SHIRT-001"},"quantity":{"type":"integer","example":5},"amount":{"type":"number","example":200},"currency_code":{"type":"string","example":"USD"},"hs_code":{"type":"string","example":"6109100040"},"country_of_origin_code":{"type":"string","example":"CN"},"weight":{"type":"number","example":0.5},"weight_unit":{"type":"string","example":"kg"},"url":{"type":"string","example":"https://example.com/products/shirt-001"}}}}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"request_id":{"type":"string","format":"uuid","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"},"error":{"type":"string","example":"invalid_request"},"message":{"type":"string","example":"Invalid request parameters"}}},"ClassifyRequest":{"type":"object","required":["description","destination_country"],"properties":{"description":{"type":"string","description":"Product description or HTS code to classify","example":"men's cotton t-shirt"},"destination_country":{"type":"string","description":"Target country for classification.\nSupported values: `us`, `ca`, `eu`, `gb`, `global` (case-insensitive)\n","example":"us"},"mode":{"type":"string","description":"Classification mode.\n- `mini`: fastest mode\n- `pro`: default balanced mode\n- `max`: highest-accuracy mode\n","enum":["mini","pro","max"],"example":"pro"},"hs_code":{"type":"string","nullable":true,"description":"Optional. An HS or HTS code to use as a classification hint. Accepts 2–10 digit codes with optional dots (e.g. `\"95\"`, `\"9503\"`, `\"9503.00.00.73\"`).\n","example":"9503"}}},"ClassifyResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"request_id":{"type":"string","format":"uuid","description":"Unique request ID for audit logging","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"},"original_description":{"type":"string","description":"The original product description submitted","example":"men's cotton t-shirt"},"customs_description":{"type":"string","description":"AI-normalized customs description","example":"men's cotton t-shirt, knitted"},"usedWebSearch":{"type":"boolean","description":"Whether web search was used to enhance classification","example":false},"execution_time":{"type":"integer","description":"Total execution time in milliseconds","example":2543},"fromCache":{"type":"boolean","description":"Whether the result was served from cache","example":false},"top_result":{"$ref":"#/components/schemas/ClassifyTopResult"},"results":{"type":"array","description":"Top classification candidates ranked by score","items":{"$ref":"#/components/schemas/ClassifyResult"}},"country":{"type":"string","description":"Country used for classification","example":"us"},"mode":{"type":"string","description":"Effective mode used for classification","enum":["mini","pro","max"],"example":"pro"},"tokens":{"type":"array","description":"Per-step token usage for cost tracking","items":{"$ref":"#/components/schemas/TokenUsage"}}}},"ClassifyTopResult":{"type":"object","nullable":true,"description":"The highest-ranked classification result","properties":{"chapter":{"$ref":"#/components/schemas/HSLevel"},"heading":{"$ref":"#/components/schemas/HSLevel"},"subheading":{"$ref":"#/components/schemas/HSLevel"},"tariff":{"$ref":"#/components/schemas/HSLevel"},"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"Confidence level based on score: High (>=0.9), Medium (>=0.75), Low (<0.75)","example":"High"},"score":{"type":"number","format":"float","description":"Classification confidence score (0-1)","example":0.95},"ai_reasoning":{"type":"string","description":"AI explanation of why this code was selected","example":"This product is a men's cotton t-shirt which falls under knitted garments..."}}},"ClassifyResult":{"type":"object","properties":{"code":{"type":"string","description":"Full HS/HTS code","example":"6109100012"},"country":{"type":"string","description":"Country nomenclature","example":"us"},"chapter":{"$ref":"#/components/schemas/HSLevel"},"heading":{"$ref":"#/components/schemas/HSLevel"},"subheading":{"$ref":"#/components/schemas/HSLevel"},"tariff":{"$ref":"#/components/schemas/HSLevel"},"import_code":{"type":"string","nullable":true,"description":"Import-specific code (if applicable)"},"score":{"type":"number","format":"float","description":"Classification confidence score (0-1)","example":0.95},"confidence":{"type":"string","enum":["High","Medium","Low"],"example":"High"},"ai_reasoning":{"type":"string","description":"AI explanation for this classification","example":"Cotton t-shirts for men are classified under heading 6109..."}}},"HSLevel":{"type":"object","description":"A level in the HS code hierarchy (chapter, heading, subheading, or tariff line)","properties":{"number":{"type":"string","description":"The code number at this level","example":"6109"},"description":{"type":"string","description":"Official description at this level","example":"T-shirts, singlets, tank tops and similar garments, knitted or crocheted"}}},"TokenUsage":{"type":"object","description":"Token usage for a single LLM call","properties":{"step":{"type":"string","description":"Pipeline step name","example":"normalize"},"model":{"type":"string","description":"Model used","example":"gemini-2.0-flash-001"},"promptTokens":{"type":"integer","example":150},"completionTokens":{"type":"integer","example":45},"totalTokens":{"type":"integer","example":195},"cost":{"type":"number","format":"float","description":"Estimated cost in USD","example":0.0002}}},"ClassifyError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Product description is required"},"request_id":{"type":"string","format":"uuid","description":"Request ID for audit logging (if authenticated)","example":"c6f398bb-1dad-40e8-a991-a22a180ad842"}}},"BulkClassifyRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"Array of products to classify (max 50)","maxItems":50,"minItems":1,"items":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"Product description to classify","example":"men's cotton t-shirt"},"destination_country":{"type":"string","description":"Target country code.\nSupported values: `us`, `ca`, `eu`, `gb`, `global` (case-insensitive)\n","example":"us"}}}}}},"BulkClassifyResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items submitted","example":10},"processed":{"type":"integer","description":"Number of items successfully processed","example":10},"results":{"type":"array","description":"Classification results in the same order as input items","items":{"$ref":"#/components/schemas/BulkClassifyResult"}},"metrics":{"$ref":"#/components/schemas/BulkClassifyMetrics"},"execution_time":{"type":"integer","description":"Total execution time in milliseconds","example":8500}}},"BulkClassifyResult":{"type":"object","properties":{"description":{"type":"string","description":"Original product description","example":"men's cotton t-shirt"},"country":{"type":"string","description":"Country used for classification","example":"us"},"hs_code":{"type":"string","description":"Best-match HS/HTS code","example":"6109100012"},"confidence_score":{"type":"number","format":"float","description":"Classification confidence score (0-1)","example":0.95},"confidence":{"type":"string","enum":["High","Medium","Low"],"example":"High"},"normalized_description":{"type":"string","description":"AI-normalized customs description","example":"men's cotton t-shirt, knitted"},"ai_reasoning":{"type":"string","description":"AI explanation for this classification"},"chapter":{"$ref":"#/components/schemas/HSLevel"},"heading":{"$ref":"#/components/schemas/HSLevel"},"subheading":{"$ref":"#/components/schemas/HSLevel"},"tariff":{"$ref":"#/components/schemas/HSLevel"}}},"BulkClassifyMetrics":{"type":"object","description":"Performance and optimization metrics for the bulk request","properties":{"totalItems":{"type":"integer","description":"Total items submitted","example":10},"uniqueItems":{"type":"integer","description":"Unique items after deduplication","example":8},"duplicates":{"type":"integer","description":"Number of duplicate items saved","example":2},"apiCalls":{"type":"integer","description":"Number of AI classification calls made","example":6},"cacheHits":{"type":"integer","description":"Number of items served from cache","example":2},"executionTime":{"type":"integer","description":"Total execution time in milliseconds","example":8500},"avgTimePerItem":{"type":"number","format":"float","description":"Average time per item in milliseconds","example":850},"costSavings":{"type":"number","format":"float","description":"Percentage of API calls saved through caching and deduplication","example":40}}},"WebhookPayload_PaymentSucceeded":{"type":"object","description":"Payload sent when a payment is successfully completed","properties":{"event":{"type":"string","enum":["payment.succeeded"],"example":"payment.succeeded"},"timestamp":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"reference":{"type":"string","example":"ORD-2024-001"},"customer_email":{"type":"string","format":"email","example":"customer@example.com"},"amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"}}},"payment":{"type":"object","properties":{"status":{"type":"string","enum":["paid"],"example":"paid"},"amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"},"paid_at":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"}}}},"example":{"event":"payment.succeeded","timestamp":"2024-01-15T10:30:00Z","order":{"id":"550e8400-e29b-41d4-a716-446655440000","reference":"ORD-2024-001","customer_email":"customer@example.com","amount":15000,"currency":"USD"},"payment":{"status":"paid","amount":15000,"currency":"USD","paid_at":"2024-01-15T10:30:00Z"}}},"WebhookPayload_PaymentFailed":{"type":"object","description":"Payload sent when a payment fails","properties":{"event":{"type":"string","enum":["payment.failed"],"example":"payment.failed"},"timestamp":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"reference":{"type":"string","example":"ORD-2024-001"},"customer_email":{"type":"string","format":"email","example":"customer@example.com"},"amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"}}},"payment":{"type":"object","properties":{"status":{"type":"string","enum":["failed"],"example":"failed"},"amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"},"paid_at":{"type":"string","nullable":true,"example":null}}}},"example":{"event":"payment.failed","timestamp":"2024-01-15T10:30:00Z","order":{"id":"550e8400-e29b-41d4-a716-446655440000","reference":"ORD-2024-001","customer_email":"customer@example.com","amount":15000,"currency":"USD"},"payment":{"status":"failed","amount":15000,"currency":"USD","paid_at":null}}},"WebhookPayload_OrderCreated":{"type":"object","description":"Payload sent when a new order is created","properties":{"event":{"type":"string","enum":["order.created"],"example":"order.created"},"timestamp":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"reference":{"type":"string","example":"ORD-2024-001"},"customer_email":{"type":"string","format":"email","example":"customer@example.com"},"customer_name":{"type":"string","example":"John Doe"},"status":{"type":"string","example":"pending"},"total_amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"},"created_at":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"}}}},"example":{"event":"order.created","timestamp":"2024-01-15T10:30:00Z","order":{"id":"550e8400-e29b-41d4-a716-446655440000","reference":"ORD-2024-001","customer_email":"customer@example.com","customer_name":"John Doe","status":"pending","total_amount":15000,"currency":"USD","created_at":"2024-01-15T10:30:00Z"}}},"WebhookPayload_OrderUpdated":{"type":"object","description":"Payload sent when an order is updated","properties":{"event":{"type":"string","enum":["order.updated"],"example":"order.updated"},"timestamp":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"reference":{"type":"string","example":"ORD-2024-001"},"customer_email":{"type":"string","format":"email","example":"customer@example.com"},"customer_name":{"type":"string","example":"John Doe"},"status":{"type":"string","example":"processing"},"total_amount":{"type":"number","example":15000},"currency":{"type":"string","example":"USD"},"created_at":{"type":"string","format":"date-time","example":"2024-01-15T10:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2024-01-15T10:30:00Z"}}},"changes":{"type":"object","properties":{"status":{"type":"object","properties":{"from":{"type":"string","example":"pending"},"to":{"type":"string","example":"processing"}}}}}},"example":{"event":"order.updated","timestamp":"2024-01-15T10:30:00Z","order":{"id":"550e8400-e29b-41d4-a716-446655440000","reference":"ORD-2024-001","customer_email":"customer@example.com","customer_name":"John Doe","status":"processing","total_amount":15000,"currency":"USD","created_at":"2024-01-15T10:00:00Z","updated_at":"2024-01-15T10:30:00Z"},"changes":{"status":{"from":"pending","to":"processing"}}}},"WebhookHeaders":{"type":"object","description":"HTTP headers included with all webhook requests","properties":{"Content-Type":{"type":"string","enum":["application/json"],"example":"application/json"},"User-Agent":{"type":"string","example":"Traddal-Webhooks/1.0"},"X-Traddal-Event":{"type":"string","description":"The event type being sent","example":"payment.succeeded"},"X-Traddal-Signature":{"type":"string","description":"HMAC SHA-256 signature of the request body (when webhook secret is configured)","example":"a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"}}}}}}