🔗

Checkout Integration

ActiveIntegrationMUSTFREE

What it does

DDP/DDU checkout flow with fraud detection and session management. Create checkout sessions that calculate total landed cost for multi-item carts, supporting up to 50 items per session with DDP, DDU, or DAP pricing modes.

Required Fields for 100% Accuracy

5 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`
`items[].productName`	string	!	Product name for each item	`Wireless Mouse`
`items[].price`	number	!	Item price (must be > 0)	`29.99`
`items[].quantity`	number	!	Quantity (must be > 0)	`1`
`items[].hsCode`	string	opt	HS code (speeds up calculation)	`8471.60`
`pricingMode`	string	opt	DDP (default), DDU, or DAP	`DDP`

Tips for Best Accuracy

✓Max 50 items per checkout session
✓Providing hsCode per item skips auto-classification and speeds up response
✓Use action=quote for price-only breakdown without creating a session

Common Mistakes

✗Items with price = 0 — price must be greater than 0
✗More than 50 items — split into multiple checkout sessions

How to use it

Create a session

POST /api/v1/checkout with origin, destination, items array, and pricing mode.

Display quote

Show the itemized cost breakdown to the buyer at checkout.

Handle pricing modes

Let buyers switch between DDP and DDU to see the difference.

Complete purchase

Use the session ID to finalize the transaction with accurate cost data.

API Reference

POST/api/v1/checkout

Request

{
  "originCountry": "CN",
  "destinationCountry": "US",
  "pricingMode": "DDP",
  "items": [
    {
      "productName": "Wireless Mouse",
      "price": 29.99,
      "quantity": 1
    },
    {
      "productName": "USB-C Cable",
      "price": 9.99,
      "quantity": 2
    }
  ]
}

Response

{
  "checkoutSessionId": "cs_abc123",
  "quote": {
    "subtotal": 49.97,
    "shipping": 8.5,
    "duty": 2.45,
    "tax": 0,
    "total": 60.92
  },
  "expiresAt": "2026-03-29T13:00:00Z"
}

cURL

curl -X POST https://potal.app/api/v1/checkout \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"originCountry":"CN","destinationCountry":"US","pricingMode":"DDP","items":[{"productName":"Wireless Mouse","price":29.99,"quantity":1}]}'

Related Features

⚙️Total Landed Cost

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

🚚DDP Quote

Compare DDP vs DDU costs with itemized fee breakdown

🔗Shopify App

Native Shopify Theme App Extension with one-click install

🔗JS Widget

Drop-in JavaScript widget for any website or checkout page

🛠️Multi-currency

Display costs in any currency with real-time conversion

Having issues?

🐛 Report a Bug ❓ Ask a Question 💡 Suggest Improvement