POTAL
v1.0REST API

API Reference

Interactive documentation for the POTAL Total Landed Cost API. Test endpoints directly from this page.

API Key:No key
BASE URL
www.potal.app/api/v1
AUTH
X-API-Key header
FORMAT
JSON
RATE LIMIT
60-120 req/min

Calculation

Calculate the total landed cost for a single item including import duties, taxes, customs fees, and the final price the buyer will pay. Supports 240 countries with real-time exchange rates.

Request

Auth Required: X-API-Key header
Body Parameters
FieldTypeReq
price
Product price in USD
numberYes
shippingPrice
Shipping cost in USD
number-
origin
Origin country ISO code (e.g., CN, US, DE)
string-
destinationCountry
Destination country ISO code
string-
zipcode
US ZIP code for state sales tax calculation
string-
productName
Product name for AI-powered HS Code classification
string-
productCategory
Product category for classification (electronics, apparel, footwear, etc.)
string-
hsCode
HS Code for precise duty calculation (6-10 digits)
string-
Request Body

Code Examples

curl -X POST https://www.potal.app/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "price": 49.99,
    "shippingPrice": 8.50,
    "origin": "CN",
    "destinationCountry": "GB",
    "productName": "Cotton T-Shirt"
  }'

Example Response

{
  "success": true,
  "data": {
    "productPrice": 49.99,
    "shippingCost": 8.50,
    "importDuty": 7.02,
    "vat": 13.10,
    "customsFees": 0,
    "totalLandedCost": 78.61,
    "currency": "USD",
    "destinationCountry": "GB",
    "originCountry": "CN",
    "isDutyFree": false,
    "breakdown": [
      { "label": "Product Price", "amount": 49.99 },
      { "label": "Shipping", "amount": 8.50 },
      { "label": "Import Duty (12.0%)", "amount": 7.02 },
      { "label": "VAT (20.0%)", "amount": 13.10 }
    ]
  },
  "meta": {
    "timestamp": "2026-03-06T12:00:00.000Z",
    "plan": "free"
  }
}

Reference

Account

Key Management

System

Error Codes

StatusCodeDescription
400BAD_REQUESTInvalid request parameters or malformed JSON body
401UNAUTHORIZEDMissing or invalid API key in X-API-Key header
403FORBIDDENAPI key does not have permission for this operation
429RATE_LIMITEDRate limit exceeded. Check X-RateLimit-* response headers
500INTERNAL_ERRORUnexpected server error. Contact support if persistent

Rate Limits & Plans

PlanPriceMonthly CallsRate Limit
Free$010030 req/min
Basic$20/mo2,00060 req/min
Pro$80/mo10,000120 req/min
Enterprise$300/mo50,000+Unlimited

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

OpenAPI 3.0 Specification
Import into Swagger UI, Postman, or any OpenAPI-compatible tool.