Create a shipment
Submit a cross-border shipment for duty and fee calculation. Returns the full fee breakdown, resolved HS codes, and a payment link for the consignee.
Request Body required
Section titled “Request Body required ”object
Brand ID or slug. Required when using an organization-level API key; optional when the key is brand-scoped.
ISO 4217 currency code for the shipment
List of items in the shipment. At least one item is required.
object
Product description for customs classification. Used together with the HS code to validate and refine the item’s classification for the destination country.
Declared value of a single unit in the shipment currency
ISO 3166-1 alpha-2 country code where the item was manufactured
Number of units of this item
6-10 digit Harmonized System code. Used together with the description for tariff calculation.
Total value for all units. If omitted, calculated as declared_value * quantity.
Shipping cost for this line item, regardless of quantity. Added to the duty/tax base by the customs engine. Internal — not shown to the consignee.
Your internal reference number for this shipment. Must be unique within the brand. When left empty or null, Duty Pro generates one automatically.
Optional carrier tracking URL for this shipment. When omitted, the brand’s (or, as a fallback, the organization’s) tracking link template is used: a URL containing a {reference} placeholder that is substituted with this shipment’s reference, e.g. https://track.example.com/{reference}. If no template is configured either, no tracking link is set.
EU IOSS registration for VAT (EU destinations only). When true, import VAT is not charged at the border. Omit to use the brand’s default setting.
Sender (shipper) details identifying the shipment’s origin.
object
Full name of the sender
Sender street address line 1
Sender street address line 2
Sender city
Sender state or province (2-letter code for US). When omitted for a US address, the state is auto-resolved from the ZIP code.
Sender postal / ZIP code
ISO 3166-1 alpha-2 origin country code
Consignee (recipient) details identifying the destination and the contact for payment notifications.
object
Full name of the consignee (recipient)
Consignee email address for payment notifications
Consignee phone number for SMS notifications
Consignee street address line 1
Consignee street address line 2
Consignee city
Consignee state or province (2-letter code for US). When omitted for a US address, the state is auto-resolved from the ZIP code.
Consignee postal / ZIP code
ISO 3166-1 alpha-2 destination country code
Responses
Section titled “ Responses ”Successful Response
object
Unique shipment identifier
Brand that owns this shipment
Brand slug identifier
Your internal reference number
Whether this shipment was created with a test API key
Per-shipment EU IOSS registration. Null when the brand default was used.
Shipment currency (ISO 4217)
Total duty amount across all items
Total tax amount across all items
Destination-country surcharges imposed in addition to duties and taxes
Total additional fees
Grand total: duties + taxes + additional country charges + additional fees
Current payment status (pending, paid, expired, etc.)
Shipment creation timestamp (UTC)
Line items with duty/tax breakdown
object
Original item description as submitted
Resolved item description after customs classification
HS code as submitted
HS code resolved by Duty Pro for the destination country
Resolved import HS code for the destination country
Resolved export HS code for the origin country
Country of origin (ISO 3166-1 alpha-2)
Declared value per unit
Number of units
Total value for all units
Shipping cost for this line item, regardless of quantity
Calculated duty amount for this item
Calculated tax amount for this item
Additional fees applied to the shipment
object
Fee type identifier
Human-readable fee name shown to the consignee
Fee amount in the shipment currency
Fee amount in its original currency before conversion
Original currency of the fee before conversion
URL for the consignee payment page. Null if no communication has been sent.
Carrier tracking URL for the consignee. Null if neither a shipment override nor a brand/organization template is configured.
Validation Error