curl --request POST \
  --url https://api.teleship.com/api/trade-engine/duties-taxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipTo": {
    "name": "John Doe",
    "email": "john@example.com",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    }
  },
  "shipFrom": {
    "name": "Acme Corp",
    "email": "shipping@example.com",
    "address": {
      "line1": "456 High St",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  },
  "commodities": [
    {
      "title": "Designer Handbag",
      "description": "Leather handbag",
      "hsCode": "4202210000",
      "quantity": 1,
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "unitWeight": {
        "value": 0.5,
        "unit": "kg"
      },
      "countryOfOrigin": "IT"
    }
  ],
  "customs": {
    "contentType": "CommercialGoods",
    "incoterms": "DDP"
  }
}
'

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ],
  "dutiesAndTaxes": {
    "price": 10.59,
    "currency": "GBP",
    "charges": [
      {
        "name": "Duty",
        "amount": 1.2,
        "currency": "GBP"
      },
      {
        "name": "VAT",
        "amount": 0.5,
        "currency": "GBP"
      }
    ],
    "commodities": [
      {
        "itemNumber": 123,
        "title": "<string>",
        "hsCode": "<string>",
        "charges": [
          {
            "name": "Duty",
            "amount": 1.2,
            "currency": "GBP",
            "rate": 0.1
          }
        ],
        "restrictions": [
          {
            "importRegion": "<string>",
            "flag": "<string>",
            "importRisk": "<string>",
            "id": "<string>",
            "countryOfOrigin": "AF",
            "hts": "<string>",
            "chapter": "<string>",
            "message": "<string>",
            "info": "<string>",
            "capture": "<string>",
            "metadata": {},
            "serviceCode": "TELESHIP-EXPEDITED-PICKUP",
            "shippingMethod": "RM-RETURN-T24",
            "restrictionLevel": "FALSE",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z"
          }
        ]
      }
    ],
    "customsDeclaration": {}
  },
  "collection": {
    "collectionId": "col_abc123",
    "trackingNumber": "TRK123456789",
    "status": "pending",
    "collectionDeadline": "2026-01-31T23:59:59Z",
    "paymentUrl": "https://duties-taxes.com/col_abc123",
    "events": [
      "<string>"
    ]
  }
}

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ]
}

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ]
}

Trade engine

Calculate duties and taxes

Calculate import duties, taxes, and customs fees for international shipments.

How it works:

Provide shipment and commodity details (origin, destination, HS codes, values)
Receive a breakdown of all applicable duties and taxes in the dutiesAndTaxes response

Additional Services:

additionalServices.postalDuties: Calculate lower postal duty rates instead of courier rates
additionalServices.taxesCollection: Create a DDU taxes collection (see below)

DDU Taxes Collection (when additionalServices.taxesCollection: true):

Requires: incoterms: DDU, trackingNumber, and shipTo.phone OR shipTo.email
Creates a taxes collection record with status pending_classification
Triggers background HS code classification and duty recalculation
Returns dutiesAndTaxes: null (final amount calculated after classification)
Returns collection object with collectionId, status, paymentUrl, and collectionDeadline
Notification channel: Both SMS and email when both provided, otherwise whichever is available
Partner receives webhook when classification completes and collection is ready for payment

Why use this? Show landed cost estimates to customers, avoid surprise fees, ensure customs compliance, and collect duties from consignees for DDU shipments.

POST

api

trade-engine

duties-taxes

curl --request POST \
  --url https://api.teleship.com/api/trade-engine/duties-taxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipTo": {
    "name": "John Doe",
    "email": "john@example.com",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postcode": "10001",
      "country": "US"
    }
  },
  "shipFrom": {
    "name": "Acme Corp",
    "email": "shipping@example.com",
    "address": {
      "line1": "456 High St",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  },
  "commodities": [
    {
      "title": "Designer Handbag",
      "description": "Leather handbag",
      "hsCode": "4202210000",
      "quantity": 1,
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "unitWeight": {
        "value": 0.5,
        "unit": "kg"
      },
      "countryOfOrigin": "IT"
    }
  ],
  "customs": {
    "contentType": "CommercialGoods",
    "incoterms": "DDP"
  }
}
'

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ],
  "dutiesAndTaxes": {
    "price": 10.59,
    "currency": "GBP",
    "charges": [
      {
        "name": "Duty",
        "amount": 1.2,
        "currency": "GBP"
      },
      {
        "name": "VAT",
        "amount": 0.5,
        "currency": "GBP"
      }
    ],
    "commodities": [
      {
        "itemNumber": 123,
        "title": "<string>",
        "hsCode": "<string>",
        "charges": [
          {
            "name": "Duty",
            "amount": 1.2,
            "currency": "GBP",
            "rate": 0.1
          }
        ],
        "restrictions": [
          {
            "importRegion": "<string>",
            "flag": "<string>",
            "importRisk": "<string>",
            "id": "<string>",
            "countryOfOrigin": "AF",
            "hts": "<string>",
            "chapter": "<string>",
            "message": "<string>",
            "info": "<string>",
            "capture": "<string>",
            "metadata": {},
            "serviceCode": "TELESHIP-EXPEDITED-PICKUP",
            "shippingMethod": "RM-RETURN-T24",
            "restrictionLevel": "FALSE",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z"
          }
        ]
      }
    ],
    "customsDeclaration": {}
  },
  "collection": {
    "collectionId": "col_abc123",
    "trackingNumber": "TRK123456789",
    "status": "pending",
    "collectionDeadline": "2026-01-31T23:59:59Z",
    "paymentUrl": "https://duties-taxes.com/col_abc123",
    "events": [
      "<string>"
    ]
  }
}

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ]
}

{
  "messages": [
    {
      "code": 123,
      "level": "error",
      "timestamp": "2024-01-01T00:00:00.00Z",
      "message": "An error occurred",
      "details": [
        "Missing required field"
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-request-id

string

x-account-id

string

Body

application/json

shipTo

object

required

Show child attributes

shipFrom

object

required

Show child attributes

commodities

object[]

required

Show child attributes

customs

object

Show child attributes

currency

enum<string>

default:GBP

Available options:

GBP,

USD,

EUR,

CAD,

AUD,

BGN,

CZK,

DKK,

HUF,

PLN,

RON,

SEK,

NZD,

SAR,

AED,

HKD,

SGD

orderTrackingReference

string

shipmentId

string

trackingNumber

string

Tracking number for the shipment. Required for DDU collection creation.

externalManifestId

string

External manifest ID for partner reference (must be unique per account)

freightCharge

object

The freight/shipping charge for VAT-on-freight calculations.

Show child attributes

consigneeCharges

object

Show child attributes

insuranceValue

object

Show child attributes

weight

object

Package weight for DDU collection

Show child attributes

dimensions

object

Package dimensions for DDU collection

Show child attributes

description

string

Shipment description

customerReference

string

Customer/partner reference number

packageType

enum<string>

Package type

Available options:

envelope,

tube,

parcel

contentType

enum<string>

Content type

Available options:

Documents,

Gift,

Sample,

Other,

CommercialGoods,

ReturnOfGoods

metadata

object

Additional metadata

additionalServices

object

Additional services for duties calculation

Show child attributes

Response

messages

object[]

required

Show child attributes

dutiesAndTaxes

object

Duties and taxes calculation result

Show child attributes

collection

object

Taxes collection details (when additionalServices.taxesCollection=true)

Show child attributes

Overview

Authentication

Shipping services

Trade engine

Taxes collections

Calculate duties and taxes

Authorizations

Headers

Body

Response