> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teleship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.




## OpenAPI

````yaml /api-reference/openapi.json post /api/trade-engine/duties-taxes
openapi: 3.0.0
info:
  title: Teleship
  description: >

    Teleship is a leading cross-border logistics provider offering seamless
    global commerce solutions through our comprehensive API.


    With Teleship's API, developers can integrate our cross-border shipping
    services, trade engine, and logistics solutions directly into their
    applications.


    **Key Features:**

    - Cross-border shipping solutions for international commerce

    - Real-time shipping rates and delivery estimates

    - End-to-end shipment tracking with detailed status updates

    - Automated customs compliance and product classification

    - Real-time event notifications through webhooks


    **Why Teleship?**

    - API-first: Developer-friendly integration with comprehensive documentation

    - Enterprise-ready: Built for businesses of all sizes

    - Secure: Enterprise-grade security and compliance

    - Integrated: Seamless connection with e-commerce, ERP, and fulfillment
    systems


    Start shipping globally with Teleship's powerful cross-border logistics API.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.teleship.com
security: []
tags: []
paths:
  /api/trade-engine/duties-taxes:
    post:
      tags:
        - Trade Engine
      summary: Calculate duties and taxes
      description: >
        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.
      operationId: calculateDutiesAndTaxes
      parameters:
        - name: x-request-id
          in: header
          required: false
          schema:
            type: string
        - name: x-account-id
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DutiesAndTaxesQuoteRequestDto'
            examples:
              Basic Calculation:
                summary: Calculate duties only (standard courier rates)
                value:
                  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
              Postal Duties:
                summary: Calculate lower postal duty rates
                value:
                  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
                  additionalServices:
                    postalDuties: true
              DDU with Taxes Collection:
                summary: Calculate duties AND create taxes collection for DDU
                description: >-
                  Creates a taxes collection record and initiates the duty
                  payment flow. Returns dutiesAndTaxes: null (final amount
                  calculated after HS code classification).
                value:
                  trackingNumber: TRK123456789
                  shipTo:
                    name: John Doe
                    email: john@example.com
                    phone: '+14155552671'
                    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: DDU
                  additionalServices:
                    taxesCollection: true
              UKToCanada:
                value:
                  shipTo:
                    name: Pat Doe
                    address:
                      line1: 778 Douglas Street
                      city: Victoria
                      postcode: V8W 2B5
                      state: BC
                      country: CA
                  shipFrom:
                    name: Manchester Store
                    address:
                      line1: Mosley Road
                      city: Manchester
                      postcode: M17 1FQ
                      country: GB
                  commodities:
                    - quantity: 3
                      title: Uptown Black Croc Fitted Over-Knee Boots
                      hsCode: '6403511000'
                      value:
                        amount: 185.13
                        currency: GBP
                      kgWeight: 0.7
                      unitWeight:
                        unit: kg
                        value: 0.7
                      sku: CL12877213039
                      countryOfOrigin: GB
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 555.39
                      currency: GBP
                  orderTrackingReference: CA-1001
              UKToAustralia:
                value:
                  shipTo:
                    name: Chris Doe
                    address:
                      line1: 1 Martin Place
                      line2: Level 5
                      city: Sydney
                      postcode: '2000'
                      state: NSW
                      country: AU
                  shipFrom:
                    name: London Store
                    address:
                      line1: Buckingham Palace Road
                      city: London
                      postcode: SW1A 1AA
                      country: GB
                  commodities:
                    - quantity: 2
                      title: Premium British Tea Set
                      hsCode: '6911101000'
                      value:
                        amount: 129.99
                        currency: GBP
                      kgWeight: 0.9
                      unitWeight:
                        unit: kg
                        value: 0.9
                      sku: TS-001-AU
                      countryOfOrigin: GB
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 259.98
                      currency: GBP
                  orderTrackingReference: AU-2001
              UKToNewZealand:
                value:
                  shipTo:
                    name: James Doe
                    address:
                      line1: 123 Lambton Quay
                      city: Wellington
                      postcode: '6011'
                      country: NZ
                  shipFrom:
                    name: Edinburgh Store
                    address:
                      line1: 1 Princes Street
                      city: Edinburgh
                      postcode: EH1 1RF
                      country: GB
                  commodities:
                    - quantity: 1
                      title: Highland Wool Blanket
                      hsCode: '6301300010'
                      value:
                        amount: 99.99
                        currency: GBP
                      kgWeight: 1.5
                      unitWeight:
                        unit: kg
                        value: 1.5
                      sku: WB-002-NZ
                      countryOfOrigin: GB
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 99.99
                      currency: GBP
                  orderTrackingReference: NZ-3001
              UKToSingapore:
                value:
                  shipTo:
                    name: Casey Doe
                    address:
                      line1: 1 Raffles Place
                      line2: '#42-01'
                      city: Singapore
                      postcode: '018956'
                      country: SG
                  shipFrom:
                    name: Oxford Store
                    address:
                      line1: High Street
                      city: Oxford
                      postcode: OX1 2JD
                      country: GB
                  commodities:
                    - quantity: 1
                      title: Designer Luxury Watch
                      hsCode: '9102210080'
                      value:
                        amount: 450
                        currency: GBP
                      kgWeight: 0.25
                      unitWeight:
                        unit: kg
                        value: 0.25
                      sku: DW-003-SG
                      countryOfOrigin: CH
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 450
                      currency: GBP
                  orderTrackingReference: SG-4001
              UKToHongKong:
                value:
                  shipTo:
                    name: Riley Doe
                    address:
                      line1: 8 Finance Street
                      line2: Unit 1502
                      city: Central
                      state: Hong Kong Island
                      country: HK
                  shipFrom:
                    name: Birmingham Store
                    address:
                      line1: New Street
                      city: Birmingham
                      postcode: B1 1AA
                      country: GB
                  commodities:
                    - quantity: 2
                      title: Sterling Silver Necklace
                      hsCode: '7113112000'
                      value:
                        amount: 280
                        currency: GBP
                      kgWeight: 0.06
                      unitWeight:
                        unit: kg
                        value: 0.06
                      sku: SN-004-HK
                      countryOfOrigin: GB
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 560
                      currency: GBP
                  orderTrackingReference: HK-5001
              UKToUAE:
                value:
                  shipTo:
                    name: Quinn Doe
                    address:
                      line1: Sheikh Zayed Road
                      line2: Boulevard Plaza Tower 1
                      city: Dubai
                      state: Dubai
                      country: AE
                  shipFrom:
                    name: Leeds Store
                    address:
                      line1: City Square
                      city: Leeds
                      postcode: LS1 1UR
                      country: GB
                  commodities:
                    - quantity: 1
                      title: Designer Luxury Handbag
                      hsCode: '4202210090'
                      value:
                        amount: 750
                        currency: GBP
                      kgWeight: 0.8
                      unitWeight:
                        unit: kg
                        value: 0.8
                      sku: LH-005-AE
                      countryOfOrigin: IT
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 750
                      currency: GBP
                  orderTrackingReference: AE-6001
              UKToSaudiArabia:
                value:
                  shipTo:
                    name: Drew Doe
                    address:
                      line1: King Fahd Road
                      line2: Al Olaya District
                      city: Riyadh
                      postcode: '12271'
                      state: Riyadh
                      country: SA
                  shipFrom:
                    name: Glasgow Store
                    address:
                      line1: George Square
                      city: Glasgow
                      postcode: G2 1DY
                      country: GB
                  commodities:
                    - quantity: 3
                      title: Savile Row Business Suits
                      hsCode: '6203110000'
                      value:
                        amount: 950
                        currency: GBP
                      kgWeight: 0.8
                      unitWeight:
                        unit: kg
                        value: 0.8
                      sku: BS-006-SA
                      countryOfOrigin: GB
                  customs:
                    contentType: CommercialGoods
                    orderTotalValue:
                      amount: 2850
                      currency: GBP
                  orderTrackingReference: SA-7001
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DutyAndTaxesRateDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessagesDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessagesDto'
      security:
        - bearer: []
components:
  schemas:
    DutiesAndTaxesQuoteRequestDto:
      type: object
      properties:
        shipTo:
          $ref: '#/components/schemas/LocationDto'
        shipFrom:
          $ref: '#/components/schemas/LocationDto'
        commodities:
          type: array
          items:
            $ref: '#/components/schemas/CommodityDataDto'
        customs:
          $ref: '#/components/schemas/CustomsDto'
        currency:
          type: string
          enum:
            - GBP
            - USD
            - EUR
            - CAD
            - AUD
            - BGN
            - CZK
            - DKK
            - HUF
            - PLN
            - RON
            - SEK
            - NZD
            - SAR
            - AED
            - HKD
            - SGD
          default: GBP
        orderTrackingReference:
          type: string
        shipmentId:
          type: string
        trackingNumber:
          type: string
          description: >-
            Tracking number for the shipment. Required for DDU collection
            creation.
        externalManifestId:
          type: string
          description: >-
            External manifest ID for partner reference (must be unique per
            account)
        freightCharge:
          description: The freight/shipping charge for VAT-on-freight calculations.
          allOf:
            - $ref: '#/components/schemas/AmountDto'
        consigneeCharges:
          $ref: '#/components/schemas/AmountDto'
        insuranceValue:
          $ref: '#/components/schemas/AmountDto'
        weight:
          description: Package weight for DDU collection
          allOf:
            - $ref: '#/components/schemas/WeightDto'
        dimensions:
          description: Package dimensions for DDU collection
          allOf:
            - $ref: '#/components/schemas/DimensionsDto'
        description:
          type: string
          description: Shipment description
        customerReference:
          type: string
          description: Customer/partner reference number
        packageType:
          type: string
          description: Package type
          enum:
            - envelope
            - tube
            - parcel
        contentType:
          type: string
          description: Content type
          enum:
            - Documents
            - Gift
            - Sample
            - Other
            - CommercialGoods
            - ReturnOfGoods
        metadata:
          type: object
          description: Additional metadata
        additionalServices:
          description: Additional services for duties calculation
          allOf:
            - $ref: '#/components/schemas/DutiesAdditionalServicesDto'
      required:
        - shipTo
        - shipFrom
        - commodities
    DutyAndTaxesRateDto:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDto'
        dutiesAndTaxes:
          description: Duties and taxes calculation result
          allOf:
            - $ref: '#/components/schemas/DutiesAndTaxesResponseDto'
        collection:
          description: >-
            Taxes collection details (when
            additionalServices.taxesCollection=true)
          allOf:
            - $ref: '#/components/schemas/TaxesCollectionResponseDto'
      required:
        - messages
    ResponseMessagesDto:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDto'
      required:
        - messages
    LocationDto:
      type: object
      properties:
        name:
          type: string
          description: The shipper's name.
        email:
          type: string
          description: Email address for the shipper.
        phone:
          type: string
          description: >-
            Phone number for the shipper. A valid local phone number including
            area code or a fully qualified international number. Drivers can use
            this to coordinate pickup with the sender.
        company:
          type: string
          description: >-
            Business name. This helps the driver successfully collect and
            deliver the parcel.
        stateTaxId:
          type: string
          description: The state tax Id
        countryTaxId:
          type: string
          description: The country tax Id. EORI number for GB, EIN number for US
        address:
          default:
            line1: ''
            city: ''
            postcode: ''
            country: GB
          allOf:
            - $ref: '#/components/schemas/AddressDto'
      required:
        - name
        - address
    CommodityDataDto:
      type: object
      properties:
        title:
          type: string
          description: Short name or title of the item.
          maxLength: 250
        description:
          type: string
          description: Detailed description of the contents for customs purposes.
          maxLength: 250
        hsCode:
          type: string
          description: >-
            A Harmonized System code for this item, appropriate for the
            destination country. Single HS tarrif code only. Must be a valid HS
            code format of 6–10 digits.
        sku:
          type: string
          description: The SKU of the item.
          maxLength: 50
        quantity:
          type: number
          description: How many of this item are in the parcel? Must be a whole number.
          default: 1
        value:
          description: The monetary value of the item.
          allOf:
            - $ref: '#/components/schemas/AmountDto'
        unitWeight:
          description: >-
            The weight of a single item. Note we will get a total weight from
            the quantity and unit weight.
          allOf:
            - $ref: '#/components/schemas/WeightDto'
        countryOfOrigin:
          type: string
          description: The country where the goods were manufactured.
          enum:
            - AF
            - AL
            - DZ
            - AS
            - AC
            - AD
            - AO
            - AI
            - AQ
            - AG
            - AR
            - AM
            - AW
            - AU
            - AT
            - AZ
            - BS
            - BH
            - BD
            - BB
            - BY
            - BE
            - BZ
            - BJ
            - BM
            - BT
            - BO
            - BA
            - BW
            - BV
            - BR
            - IO
            - BN
            - BG
            - BF
            - BI
            - KH
            - CM
            - CA
            - CV
            - KY
            - CF
            - TD
            - CL
            - CN
            - CX
            - CC
            - CO
            - KM
            - CG
            - CD
            - CK
            - CR
            - CI
            - HR
            - CU
            - CY
            - CZ
            - DK
            - DJ
            - DM
            - DO
            - EC
            - EG
            - EL
            - SV
            - GQ
            - ER
            - EE
            - ET
            - FK
            - FO
            - FJ
            - FI
            - FR
            - GF
            - PF
            - TF
            - GA
            - GM
            - GE
            - DE
            - GH
            - GI
            - GR
            - GL
            - GD
            - GP
            - GU
            - GT
            - GG
            - GN
            - GW
            - GY
            - HT
            - HM
            - VA
            - HN
            - HK
            - HU
            - IS
            - IN
            - ID
            - IR
            - IQ
            - IE
            - IM
            - IL
            - IT
            - JM
            - JP
            - JE
            - JO
            - KZ
            - KE
            - KI
            - KP
            - KR
            - KW
            - KG
            - LA
            - LV
            - LB
            - LS
            - LR
            - LY
            - LI
            - LT
            - LU
            - MO
            - MK
            - MG
            - MW
            - MY
            - MV
            - ML
            - MT
            - MH
            - MQ
            - MR
            - MU
            - YT
            - MX
            - FM
            - MD
            - MC
            - MN
            - ME
            - MS
            - MA
            - MZ
            - MM
            - NA
            - NR
            - NP
            - NL
            - AN
            - NC
            - NZ
            - NI
            - NE
            - NG
            - NU
            - NF
            - MP
            - 'NO'
            - OM
            - PK
            - PW
            - PS
            - PA
            - PG
            - PY
            - PE
            - PH
            - PN
            - PL
            - PT
            - PR
            - QA
            - RE
            - RO
            - RU
            - RW
            - SH
            - KN
            - LC
            - PM
            - VC
            - WS
            - SM
            - ST
            - SA
            - SN
            - RS
            - SC
            - SL
            - SG
            - SK
            - SI
            - SB
            - SO
            - ZA
            - GS
            - ES
            - LK
            - SD
            - SR
            - SJ
            - SZ
            - SE
            - CH
            - SY
            - TW
            - TJ
            - TZ
            - TH
            - TL
            - TG
            - TK
            - TO
            - TT
            - TN
            - TR
            - TM
            - TC
            - TV
            - UG
            - UA
            - AE
            - GB
            - US
            - UM
            - UY
            - UZ
            - VU
            - VE
            - VN
            - VG
            - VI
            - WF
            - EH
            - YE
            - ZM
            - ZW
        category:
          type: string
          description: The category of the item.
        imageUrl:
          type: string
          description: The URL of the product image.
        productUrl:
          type: string
          description: The URL of the product page.
        productId:
          type: string
          description: The product ID of the item.
        variantId:
          type: string
          description: The variant ID of the item.
        compliance:
          description: The advanced details of the commodity.
          allOf:
            - $ref: '#/components/schemas/CommodityComplianceDto'
        metadata:
          type: object
          additionalProperties: true
          description: Metadata about the commodity.
          default: {}
      required:
        - title
        - quantity
        - value
        - unitWeight
    CustomsDto:
      type: object
      properties:
        contentType:
          type: string
          description: The description of the contents for customs purposes.
          enum:
            - Documents
            - Gift
            - Sample
            - Other
            - CommercialGoods
            - ReturnOfGoods
        incoterms:
          type: string
          description: The incoterms for the shipment.
          enum:
            - DDP
            - DDU
        invoiceNumber:
          type: string
          description: The invoice number for the shipment.
        invoiceDate:
          format: date-time
          type: string
          description: The date of the invoice.
        orderId:
          type: string
          description: The order ID of the shipment
        orderTotalValue:
          description: The total value of the invoice.
          allOf:
            - $ref: '#/components/schemas/AmountDto'
        certified:
          type: boolean
          description: Whether the contents are cerified.
        signedBy:
          type: string
          description: The name of the person who certifies the customs content.
        EORI:
          type: string
          description: The EORI number of the seller.
        IOSS:
          type: string
          description: The IOSS number of the seller.
        VAT:
          type: string
          description: The VAT number of the seller.
        EIN:
          type: string
          description: The EIN number of the seller.
        VOECNUMBER:
          type: string
          description: The Norwegian VAT number of the seller.
        SWISSVAT:
          type: string
          description: The Swiss VAT number of the seller.
        KAR_VAT:
          type: string
          description: K number of the seller.
        CA_GST:
          type: string
          description: Canadian GST number of the seller.
        AU_GST:
          type: string
          description: Australian GST number of the seller.
        NZ_GST:
          type: string
          description: New Zealand GST number of the seller.
        JPConsumptionTax:
          type: string
          description: The Swiss VAT number of the seller.
        GPSRContactInfo:
          type: string
          description: The contact information for the GPSR.
        importerOfRecord:
          description: The importer of record.
          allOf:
            - $ref: '#/components/schemas/LocationDto'
      required:
        - contentType
    AmountDto:
      type: object
      properties:
        amount:
          type: number
          description: A decimal value.
          example: '15.0'
        currency:
          type: string
          description: The currency of the amount.
          enum:
            - GBP
            - USD
            - EUR
            - CAD
            - AUD
            - BGN
            - CZK
            - DKK
            - HUF
            - PLN
            - RON
            - SEK
            - NZD
            - SAR
            - AED
            - HKD
            - SGD
          default: GBP
      required:
        - amount
        - currency
    WeightDto:
      type: object
      properties:
        value:
          type: number
          description: The decimal value of the item weight.
          default: '1.0'
          minimum: 0.001
        unit:
          type: string
          description: The unit of measurement for the weight
          enum:
            - kg
            - lb
          default: kg
      required:
        - value
        - unit
    DimensionsDto:
      type: object
      properties:
        length:
          type: number
          description: The decimal value of the length of the item
          default: '40.0'
        width:
          type: number
          description: The decimal value of the width of the item
          default: '30.0'
        height:
          type: number
          description: The decimal value of the height of the item
          default: '16.0'
        unit:
          type: string
          description: The unit of measurement for the dimensions
          enum:
            - cm
            - in
          default: cm
      required:
        - length
        - width
        - height
        - unit
    DutiesAdditionalServicesDto:
      type: object
      properties:
        postalDuties:
          type: boolean
          description: Calculate postal duties (lower duty rates for postal shipments)
          default: false
        taxesCollection:
          type: boolean
          description: >-
            Create a taxes collection for DDU duty capture. Requires:
            trackingNumber, incoterms=DDU, phone or email
          default: false
    ErrorResponseDto:
      type: object
      properties:
        code:
          type: number
        level:
          type: string
          enum:
            - error
            - warning
            - info
          example: error
          description: Error level
          default: error
        timestamp:
          format: date-time
          type: string
          example: '2024-01-01T00:00:00.00Z'
        message:
          type: string
          example: An error occurred
        details:
          example:
            - Missing required field
          type: array
          items:
            type: string
      required:
        - code
        - level
        - timestamp
        - message
        - details
    DutiesAndTaxesResponseDto:
      type: object
      properties:
        price:
          type: number
          description: The total amount of duties and taxes.
          example: 10.59
        currency:
          type: string
          description: The currency of the duties and taxes.
          enum:
            - GBP
            - USD
            - EUR
            - CAD
            - AUD
            - BGN
            - CZK
            - DKK
            - HUF
            - PLN
            - RON
            - SEK
            - NZD
            - SAR
            - AED
            - HKD
            - SGD
          example: GBP
        charges:
          description: >-
            Breakdown of duty and tax charges. These items summed equal the
            total price.
          example:
            - name: Duty
              amount: 1.2
              currency: GBP
            - name: VAT
              amount: 0.5
              currency: GBP
          type: array
          items:
            $ref: '#/components/schemas/ChargeDto'
        commodities:
          description: Classified and dutiable commodities with per-item duty breakdown
          type: array
          items:
            $ref: '#/components/schemas/CommodityInfoDto'
        customsDeclaration:
          type: object
          description: Customs declaration details
      required:
        - price
        - currency
        - charges
    TaxesCollectionResponseDto:
      type: object
      properties:
        collectionId:
          type: string
          description: Unique collection ID
          example: col_abc123
        trackingNumber:
          type: string
          description: Tracking number for the shipment
          example: TRK123456789
        status:
          type: string
          description: Collection status
          example: pending
        collectionDeadline:
          type: string
          description: Deadline for duty payment
          format: date-time
          example: '2026-01-31T23:59:59Z'
        events:
          description: Collection events/timeline
          type: array
          items:
            type: string
        paymentUrl:
          type: string
          description: Payment URL for consignee to pay duties
          example: https://duties-taxes.com/col_abc123
      required:
        - collectionId
        - trackingNumber
        - status
        - collectionDeadline
        - paymentUrl
    AddressDto:
      type: object
      properties:
        line1:
          type: string
          description: >-
            The street address for the location. Do not include the postcode,
            state, or suburb in this field.
        line2:
          type: string
          description: Second line of the street address for the location.
        city:
          type: string
          description: >-
            City or town of the location. In certain regions the name here is
            validated against the postcode, so must be valid and match.
        state:
          type: string
          description: State, province, or territory of the location.
        country:
          type: string
          description: Country for the recipient.
          enum:
            - AF
            - AL
            - DZ
            - AS
            - AC
            - AD
            - AO
            - AI
            - AQ
            - AG
            - AR
            - AM
            - AW
            - AU
            - AT
            - AZ
            - BS
            - BH
            - BD
            - BB
            - BY
            - BE
            - BZ
            - BJ
            - BM
            - BT
            - BO
            - BA
            - BW
            - BV
            - BR
            - IO
            - BN
            - BG
            - BF
            - BI
            - KH
            - CM
            - CA
            - CV
            - KY
            - CF
            - TD
            - CL
            - CN
            - CX
            - CC
            - CO
            - KM
            - CG
            - CD
            - CK
            - CR
            - CI
            - HR
            - CU
            - CY
            - CZ
            - DK
            - DJ
            - DM
            - DO
            - EC
            - EG
            - EL
            - SV
            - GQ
            - ER
            - EE
            - ET
            - FK
            - FO
            - FJ
            - FI
            - FR
            - GF
            - PF
            - TF
            - GA
            - GM
            - GE
            - DE
            - GH
            - GI
            - GR
            - GL
            - GD
            - GP
            - GU
            - GT
            - GG
            - GN
            - GW
            - GY
            - HT
            - HM
            - VA
            - HN
            - HK
            - HU
            - IS
            - IN
            - ID
            - IR
            - IQ
            - IE
            - IM
            - IL
            - IT
            - JM
            - JP
            - JE
            - JO
            - KZ
            - KE
            - KI
            - KP
            - KR
            - KW
            - KG
            - LA
            - LV
            - LB
            - LS
            - LR
            - LY
            - LI
            - LT
            - LU
            - MO
            - MK
            - MG
            - MW
            - MY
            - MV
            - ML
            - MT
            - MH
            - MQ
            - MR
            - MU
            - YT
            - MX
            - FM
            - MD
            - MC
            - MN
            - ME
            - MS
            - MA
            - MZ
            - MM
            - NA
            - NR
            - NP
            - NL
            - AN
            - NC
            - NZ
            - NI
            - NE
            - NG
            - NU
            - NF
            - MP
            - 'NO'
            - OM
            - PK
            - PW
            - PS
            - PA
            - PG
            - PY
            - PE
            - PH
            - PN
            - PL
            - PT
            - PR
            - QA
            - RE
            - RO
            - RU
            - RW
            - SH
            - KN
            - LC
            - PM
            - VC
            - WS
            - SM
            - ST
            - SA
            - SN
            - RS
            - SC
            - SL
            - SG
            - SK
            - SI
            - SB
            - SO
            - ZA
            - GS
            - ES
            - LK
            - SD
            - SR
            - SJ
            - SZ
            - SE
            - CH
            - SY
            - TW
            - TJ
            - TZ
            - TH
            - TL
            - TG
            - TK
            - TO
            - TT
            - TN
            - TR
            - TM
            - TC
            - TV
            - UG
            - UA
            - AE
            - GB
            - US
            - UM
            - UY
            - UZ
            - VU
            - VE
            - VN
            - VG
            - VI
            - WF
            - EH
            - YE
            - ZM
            - ZW
        postcode:
          type: string
          description: Postcode, postal code, or ZIP code of the location.
        isResidential:
          type: boolean
          description: Whether the address is residential.
      required:
        - line1
        - country
    CommodityComplianceDto:
      type: object
      properties:
        isControlGood:
          type: boolean
          description: Whether the commodity is controlled.
        controlType:
          type: string
          description: The type of control for the commodity.
          example: HealthRegulated
        regulatoryAgency:
          type: string
          description: The regulatory agencies for the commodity.
          example: FDA
        regulatoryProgram:
          type: string
          description: The regulatory program for the commodity.
          example: Food Safety
        regulatoryCategoryCode:
          type: string
          description: The regulatory category code for the commodity.
          example: 21-CFR-XYZ
        EIN:
          type: string
          description: The EIN of the seller.
        iossNumber:
          type: string
          description: The IOSS number of the seller.
        importLicenseNumber:
          type: string
          description: The license number of the seller.
        certificationType:
          type: string
          description: The certification type for the commodity.
          example: CE
        certificationReference:
          type: string
          description: The certificate number of the seller.
          example: CE-DECL-12345
    ChargeDto:
      type: object
      properties:
        amount:
          type: number
          description: A decimal value.
          example: '15.0'
        currency:
          type: string
          description: The currency of the amount.
          enum:
            - GBP
            - USD
            - EUR
            - CAD
            - AUD
            - BGN
            - CZK
            - DKK
            - HUF
            - PLN
            - RON
            - SEK
            - NZD
            - SAR
            - AED
            - HKD
            - SGD
          default: GBP
        name:
          type: string
          description: The name of the charge.
        rate:
          type: number
          description: The rate of the charge (for VAT and duty charges).
        code:
          type: string
          description: The code of the charge.
      required:
        - name
    CommodityInfoDto:
      type: object
      properties:
        itemNumber:
          type: number
          description: The item number of the commodity.
        title:
          type: string
          description: Short name or title of the item.
          maxLength: 250
        hsCode:
          type: string
          description: The HS (Harmonized System) code used for duty calculation.
        charges:
          description: Breakdowns of the components of the price.
          example:
            - name: Duty
              amount: 1.2
              currency: GBP
              rate: 0.1
          type: array
          items:
            $ref: '#/components/schemas/ChargeDto'
        restrictions:
          description: The restrictions for the commodity.
          type: array
          items:
            $ref: '#/components/schemas/RestrictionFlagsEntryDto'
      required:
        - itemNumber
        - title
    RestrictionFlagsEntryDto:
      type: object
      properties:
        id:
          type: string
        importRegion:
          type: string
          description: The import region
        flag:
          type: string
          description: The restriction flag status
        importRisk:
          type: string
          description: The import risk level
        countryOfOrigin:
          $ref: '#/components/schemas/Country'
        hts:
          type: string
          description: The hts information
        chapter:
          type: string
          description: The chapter information
        message:
          type: string
          description: Detailed restriction message
        info:
          type: string
          description: Additional information
        capture:
          type: string
          description: Capture type
        metadata:
          type: object
          description: Additional metadata
        serviceCode:
          type: string
          description: Service code for route-specific restrictions
          example: TELESHIP-EXPEDITED-PICKUP
        shippingMethod:
          type: string
          description: Shipping method for route-specific restrictions
          example: RM-RETURN-T24
        restrictionLevel:
          $ref: '#/components/schemas/RestrictionLevel'
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - importRegion
        - flag
        - importRisk
    Country:
      type: string
      description: The country of origin
      enum:
        - AF
        - AL
        - DZ
        - AS
        - AC
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - EL
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - AN
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - SH
        - KN
        - LC
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
    RestrictionLevel:
      type: string
      description: Restriction level for this commodity
      enum:
        - 'FALSE'
        - 'TRUE'
        - ACCOUNT
        - All
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````