POTAL

Seller Integration Hub

Empower your store with real-time global shipping and tax calculations

Add POTAL to your store in 2 minutes. No backend integration required.

Quick Start

Copy and paste this code snippet into your product page HTML. Our widget will automatically calculate accurate shipping costs and taxes in real-time.

View Full Quick Start Guide →
<!-- POTAL Widget -->
<script src="https://www.potal.app/widget/potal-widget.js"></script>

<!-- Embed the widget with your API key -->
<div
  data-potal-widget
  data-api-key="YOUR_API_KEY"
  data-product-name="Your Product Name"
  data-price="99.99"
  data-shipping="15.00"
  data-origin="US"
  data-theme="light"
></div>
View Full Docs →

Try It Live

Change the parameters below and see the request and response update in real-time. Mock data — sign up for a free API key to make real calls.

Parameters

Request (cURL)
curl -X POST https://www.potal.app/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "from_country": "CN",
    "to_country": "US",
    "hs_code": "6109.10",
    "value": 49.99,
    "currency": "USD"
  }'

Click “Send Request” to see the response

API Reference

Integrate directly with our REST API for custom implementations. All endpoints require authentication with your API key.

POST

/api/v1/calculate

Calculate shipping cost, duties, and taxes for a single product.

Request:

price, shipping, origin, destination

Response:

total_cost, tax, duties

POST

/api/v1/calculate/batch

Calculate for up to 100 products in a single request.

Request:

items: array of products

Response:

results: array

GET

/api/v1/countries

Get list of supported countries. Public endpoint, no auth required.

Request:

No parameters

Response:

countries: array

Need more details? View Full API Documentation →

Authentication

All API requests (except public endpoints) require authentication via the X-API-Key header.

API Key Format

pk_live_... — Publishable key (widget embed, client-side)
sk_live_... — Secret key (server-side only, never expose in frontend)

Error Codes

StatusMeaningSolution
401Missing or invalid API keyCheck X-API-Key header is set correctly
403Plan limit exceeded or key disabledUpgrade your plan or contact support
429Rate limit exceededWait and retry, or upgrade for higher limits
cURL
curl -X POST https://www.potal.app/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "from_country": "CN",
    "to_country": "US",
    "hs_code": "6109.10",
    "value": 25.00,
    "currency": "USD"
  }'

Widget Customization

Customize the widget behavior and appearance to match your store's design.

Data Attributes

data-api-key

Your POTAL API key (required)

data-product-name

Product name for tracking

data-price

Product price in USD

data-shipping

Base shipping cost in USD

data-origin

Origin country code (e.g., US, CN)

data-theme

light or dark mode

Theme Options

Light Theme
data-theme="light"
Dark Theme
data-theme="dark"

Callback Events

onCalculated

Fired when calculation completes

onError

Fired when error occurs

onChange

Fired when user changes selection

Ready to Get Started?

Integrate POTAL today and start offering real shipping calculations to your customers.