🚚

Shipping Rates

ActiveShippingFREE

What it does

Compare shipping rates across 8 carriers including DHL, FedEx, UPS, USPS, Royal Mail, and more. Get real-time quotes with estimated delivery times, and POTAL recommends the cheapest, fastest, and best-value options.

Required Fields for 100% Accuracy

3 required / 7 total

Field	Type	Required	Description	Example
`originCountry`	string	!	Origin country (ISO 2-letter code)	`CN`
`destinationCountry`	string	!	Destination country (ISO 2-letter code)	`US`
`weightKg`	number	!	Package weight in kg (must be > 0)	`2.5`
`declaredValue`	number	opt	Declared shipment value for insurance	`100`
`lengthCm`	number	opt	Package length in cmAll 3 dimensions needed for dimensional weight calculation.	`30`
`widthCm`	number	opt	Package width in cm	`20`
`heightCm`	number	opt	Package height in cm	`15`

Tips for Best Accuracy

✓originCountry + destinationCountry + weightKg are all required
✓Providing all 3 dimensions enables dimensional weight — carriers bill the higher of actual vs dimensional
✓declaredValue affects insurance cost estimation

Common Mistakes

✗Providing only 1 or 2 dimensions — all 3 (length, width, height) are needed for dimensional weight
✗Setting weightKg to 0 — must be greater than 0
✗Using snake_case and camelCase inconsistently — both are accepted but pick one style

How to use it

Specify route

Provide origin country, destination country, and package weight.

Add dimensions

Include package dimensions for accurate dimensional weight pricing.

Get quotes

POST /api/v1/shipping/rates returns rates from all available carriers.

Use recommendations

Check the recommendation field for cheapest, fastest, and best-value options.

API Reference

POST/api/v1/shipping/rates

Request

{
  "originCountry": "CN",
  "destinationCountry": "US",
  "weightKg": 2.5,
  "declaredValue": 100,
  "lengthCm": 30,
  "widthCm": 20,
  "heightCm": 15
}

Response

{
  "rates": [
    {
      "carrier": "DHL Express",
      "service": "Express Worldwide",
      "rate": 45.5,
      "estimatedDays": 3
    },
    {
      "carrier": "FedEx",
      "service": "International Economy",
      "rate": 38.2,
      "estimatedDays": 5
    },
    {
      "carrier": "UPS",
      "service": "Worldwide Expedited",
      "rate": 42,
      "estimatedDays": 4
    }
  ],
  "recommendation": {
    "cheapest": {
      "carrier": "FedEx",
      "rate": 38.2
    },
    "fastest": {
      "carrier": "DHL Express",
      "estimatedDays": 3
    }
  },
  "totalOptions": 3
}

cURL

curl -X POST https://potal.app/api/v1/shipping/rates \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"originCountry":"CN","destinationCountry":"US","weightKg":2.5,"declaredValue":100}'

Related Features

🚚Carrier Integration

Live carrier API connections for real-time rate quotes

🚚DDP Quote

Compare DDP vs DDU costs with itemized fee breakdown

🚚Dimensional Weight

Calculate dimensional weight for accurate shipping cost estimates

⚙️Total Landed Cost

Get the full import cost including duties, taxes, fees, and shipping

🚚Label Generation

Generate 4x6 shipping labels as PDF with barcodes

Having issues?

🐛 Report a Bug ❓ Ask a Question 💡 Suggest Improvement