How to Integrate POTAL Landed Cost API: Quick Start for Developers

Get up and running with the POTAL Landed Cost API in under 5 minutes. This guide covers API key setup, your first API call, SDK installation, and production best practices.

Step 1: Get Your API Key

1. Sign up at potal.app (no credit card required)
2. Go to Dashboard → API Keys
3. Click "Create Key" to generate your keys:
   • pk_live_... — Publishable key (client-side, rate-limited)
   • sk_live_... — Secret key (server-side, full access)

The Free plan includes 200 API calls/month with access to all features.

Step 2: Your First API Call

cURL

curl -X POST https://potal.app/api/v1/calculate \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Wireless Bluetooth Earbuds",
    "hs_code": "8518.30",
    "origin_country": "CN",
    "destination_country": "DE",
    "value": 49.99,
    "currency": "USD"
  }'

JavaScript / TypeScript

import { PotalClient } from '@potal/sdk';

const potal = new PotalClient('sk_live_YOUR_KEY');

const result = await potal.calculate({
  product_name: 'Wireless Bluetooth Earbuds',
  hs_code: '8518.30',
  origin_country: 'CN',
  destination_country: 'DE',
  value: 49.99,
});

console.log(result.total_landed_cost);
console.log(result.breakdown);

Python

from potal import PotalClient

client = PotalClient("sk_live_YOUR_KEY")

result = client.calculate(
    product_name="Wireless Bluetooth Earbuds",
    hs_code="8518.30",
    origin_country="CN",
    destination_country="DE",
    value=49.99,
)

print(result.total_landed_cost)
print(result.breakdown)

Step 3: Understanding the Response

{
  "total_landed_cost": 72.34,
  "breakdown": {
    "product_value": 49.99,
    "shipping": 0.00,
    "import_duty": 0.00,
    "vat_gst": 9.50,
    "customs_fee": 0.00,
    "insurance": 0.00
  },
  "duty_rate": 0.0,
  "vat_rate": 19.0,
  "de_minimis_applied": true,
  "fta_available": false,
  "hs_code": "8518.30",
  "currency": "USD",
  "destination_country": "DE"
}

• total_landed_cost — The complete cost including all duties, taxes, and fees
• breakdown — Itemized cost components
• de_minimis_applied — Whether the shipment falls below the duty-free threshold
• fta_available — Whether a Free Trade Agreement preferential rate exists
• duty_rate / vat_rate — Applied rates as percentages

Step 4: HS Code Classification

Don't know the HS Code? Use the classification endpoint:

curl -X POST https://potal.app/api/v1/classify \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Wireless Bluetooth Earbuds",
    "material": "plastic",
    "category": "electronics"
  }'

Step 5: MCP Server for AI Agents

If you're building AI agents, POTAL is available as an MCP server:

npx potal-mcp-server

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "potal": {
      "command": "npx",
      "args": ["potal-mcp-server"],
      "env": {
        "POTAL_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Step 6: Error Handling

Common error codes and how to handle them:

• 401 Unauthorized — Invalid or missing API key. Check your Authorization header
• 429 Too Many Requests — Rate limit exceeded. Check X-RateLimit-Remaining header. Free: 30 req/min, Basic: 60, Pro: 300, Enterprise: 1,000
• 400 Bad Request — Missing required fields. The response body includes which fields are missing
• 402 Payment Required — Monthly quota exceeded on Free plan. Upgrade or wait for reset

Production Checklist

• Use sk_live_ keys on the server, pk_live_ on the client
• Implement retry logic with exponential backoff for 5xx errors
• Cache results by HS code + origin + destination to minimize API calls
• Monitor usage via the Dashboard → Analytics page
• Set up webhook notifications for quota alerts