Customs

The Customs API provides DDP (Delivered Duty Paid) calculations for international shipments. Calculate duties, taxes, and total landed costs for 170+ countries with support for multiple customs regimes.

All endpoints require authentication via Bearer token with customs:read or customs:write scope.

POST/v1/customs/calculate

Calculate DDP

Calculate duties and taxes for a single item shipment. The API automatically selects the optimal customs regime or allows you to specify one.

Required attributes

Name
destination_country
Type
string
Description
Destination country (2-letter ISO code).
Name
declared_value
Type
number
Description
Item value for customs.

Optional attributes

Name
origin_country
Type
string
Description
Origin country (2-letter ISO code, default: US).
Name
currency
Type
string
Description
Value currency (default: USD).
Name
weight
Type
number
Description
Item weight in kilograms.
Name
hs_code
Type
string
Description
HS/NCM code for duty rate lookup.
Name
freight
Type
number
Description
Freight/shipping cost.
Name
insurance
Type
number
Description
Insurance cost.
Name
regime
Type
string
Description
Customs regime: auto (default), personal, or commercial.
Name
compare_regimes
Type
boolean
Description
Return calculations for all applicable regimes.

Request

POST

/v1/customs/calculate

curl -X POST https://app.price2b.com/api/v1/customs/calculate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_country": "AR",
    "origin_country": "CN",
    "declared_value": 100.00,
    "currency": "USD",
    "weight": 0.5,
    "hs_code": "8518300000",
    "freight": 15.00,
    "insurance": 5.00,
    "regime": "auto"
  }'

Response

{
  "success": true,
  "data": {
    "calculation_id": "CALC-2026-001",
    "destination_country": "AR",
    "regime_used": "PEF_AR",
    "regime_name": "Pequeño Envío Familiar",
    "values": {
      "declared_value": 100.00,
      "freight": 15.00,
      "insurance": 5.00,
      "fob_value": 100.00,
      "cif_value": 120.00,
      "currency": "USD"
    },
    "duties_and_taxes": {
      "import_duty": 0.00,
      "iva": 25.20,
      "statistical_tax": 3.60,
      "other_taxes": 0.00,
      "total_taxes": 28.80,
      "currency": "USD"
    },
    "totals": {
      "ddp_value": 148.80,
      "amount_to_pay": 28.80,
      "currency": "USD"
    },
    "breakdown": [
      {
        "tax_name": "IVA",
        "rate": 21.0,
        "base": 120.00,
        "amount": 25.20
      },
      {
        "tax_name": "Tasa Estadística",
        "rate": 3.0,
        "base": 120.00,
        "amount": 3.60
      }
    ],
    "notes": [
      "PEF regime applied: $400 franchise threshold",
      "No import duty under $400 threshold"
    ]
  }
}

POST/v1/customs/calculate/batch

Batch calculate

Calculate DDP for multiple items in a single request. Freight costs are allocated proportionally by value or weight.

Required attributes

Name
destination_country
Type
string
Description
Destination country (2-letter ISO code).
Name
items
Type
array
Description
Array of items to calculate.

Optional attributes

Name
freight
Type
number
Description
Total freight cost to allocate.
Name
insurance
Type
number
Description
Total insurance cost to allocate.
Name
freight_allocation
Type
string
Description
Allocation method: by_value (default) or by_weight.

Request

POST

/v1/customs/calculate/batch

curl -X POST https://app.price2b.com/api/v1/customs/calculate/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_country": "AR",
    "items": [
      {
        "item_id": "ITEM-001",
        "origin_country": "CN",
        "declared_value": 100.00,
        "weight": 0.5,
        "hs_code": "8518300000"
      },
      {
        "item_id": "ITEM-002",
        "origin_country": "US",
        "declared_value": 250.00,
        "weight": 1.2,
        "hs_code": "6110200000"
      }
    ],
    "freight": 25.00,
    "insurance": 10.00,
    "freight_allocation": "by_value"
  }'

Response

{
  "success": true,
  "data": {
    "destination_country": "AR",
    "items": [
      {
        "item_id": "ITEM-001",
        "declared_value": 100.00,
        "allocated_freight": 7.14,
        "cif_value": 110.00,
        "duties_and_taxes": 23.10,
        "ddp_value": 133.10
      },
      {
        "item_id": "ITEM-002",
        "declared_value": 250.00,
        "allocated_freight": 17.86,
        "cif_value": 275.00,
        "duties_and_taxes": 57.75,
        "ddp_value": 332.75
      }
    ],
    "totals": {
      "declared_value": 350.00,
      "freight": 25.00,
      "insurance": 10.00,
      "total_duties_taxes": 80.85,
      "total_ddp": 465.85,
      "currency": "USD"
    }
  }
}

GET/v1/customs/rates/:country

Get country rates

Get current tax rates and de minimis thresholds for a specific country.

Request

GET

/v1/customs/rates/AR

curl https://app.price2b.com/api/v1/customs/rates/AR \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "country": "AR",
    "country_name": "Argentina",
    "last_updated": "2026-01-15",
    "de_minimis": {
      "threshold": 400.00,
      "currency": "USD",
      "regime": "PEF",
      "notes": "Personal regime, 5 shipments/year limit"
    },
    "standard_rates": {
      "import_duty_range": "0-35%",
      "iva": 21.0,
      "statistical_tax": 3.0,
      "impuesto_pais": 0.0
    },
    "available_regimes": [
      {
        "code": "PEF_AR",
        "name": "Pequeño Envío Familiar",
        "max_value": 400.00
      },
      {
        "code": "COURIER_AR",
        "name": "Courier Regime",
        "max_value": 3000.00
      },
      {
        "code": "GENERAL",
        "name": "General Regime",
        "max_value": null
      }
    ]
  }
}

GET/v1/customs/hs-codes/lookup

Lookup HS code

Look up HS/NCM code information including duty rates and restrictions.

Query parameters

Name
code
Type
string
Description
HS code to lookup (6-12 digits).
Name
country
Type
string
Description
Country for country-specific rates (2-letter ISO).
Name
search
Type
string
Description
Text search in HS code descriptions.

Request

GET

/v1/customs/hs-codes/lookup

curl -G https://app.price2b.com/api/v1/customs/hs-codes/lookup \
  -H "Authorization: Bearer {token}" \
  -d code=8518300000 \
  -d country=AR

Response

{
  "success": true,
  "data": {
    "hs_code": "8518300000",
    "chapter": "85",
    "heading": "8518",
    "description": "Headphones and earphones, whether or not combined with a microphone",
    "duty_rate": 20.0,
    "unit": "u",
    "country_specific": {
      "country": "AR",
      "ncm_code": "8518.30.00",
      "duty_rate": 20.0,
      "iva": 21.0,
      "additional_taxes": []
    },
    "additional_info": {
      "requires_license": false,
      "restricted": false,
      "notes": null
    }
  }
}

POST/v1/customs/calculate

Compare regimes

To compare all available customs regimes for a shipment, set compare_regimes: true in your calculation request.

Request

POST

/v1/customs/calculate

curl -X POST https://app.price2b.com/api/v1/customs/calculate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_country": "AR",
    "declared_value": 300.00,
    "weight": 1.0,
    "hs_code": "8518300000",
    "compare_regimes": true
  }'

Response

{
  "success": true,
  "data": {
    "recommended_regime": "PEF_AR",
    "regimes": [
      {
        "code": "PEF_AR",
        "name": "Pequeño Envío Familiar",
        "eligible": true,
        "total_taxes": 72.60,
        "ddp_value": 372.60,
        "savings_vs_commercial": 28.50
      },
      {
        "code": "COURIER_AR",
        "name": "Courier Regime",
        "eligible": true,
        "total_taxes": 85.00,
        "ddp_value": 385.00
      },
      {
        "code": "GENERAL",
        "name": "General Regime",
        "eligible": true,
        "total_taxes": 101.10,
        "ddp_value": 401.10
      }
    ]
  }
}

Supported countries

The Customs API supports DDP calculations for 170+ countries. Here are the most common destinations:

Code	Country	De Minimis	Notes
AR	Argentina	$400 (PEF)	5 shipments/year limit
BR	Brazil	Platform-based	Remessa Conforme program
CL	Chile	$30	6% flat + 19% IVA
MX	Mexico	$50 (T-MEC)	Non-TMEC: 33.5%
US	USA	$0	Section 321 eliminated
CA	Canada	CAD $20/40	CUSMA: $150
CO	Colombia	$200	19% IVA
PE	Peru	$200	18% IGV
UK	United Kingdom	£135	20% VAT
DE	Germany	€150	19% VAT

See full country coverage in Analytics API