Skip to content

Get a shipment

GET
/api/shipments/{shipment_ref}

Look up a shipment by its id or reference fields. Scoped to the API key’s organization, brand (for brand-scoped keys), and live/test mode. For organization-scoped keys, references that collide across brands resolve to the most recently created shipment.

shipment_ref
required
Shipment ID or reference
string

Successful Response

object
id
required
Id

Unique shipment identifier

string format: uuid
brand_id
required
Brand Id

Brand that owns this shipment

string format: uuid
brand_slug
Brand Slug

Brand slug identifier

string | null
reference
required
Reference

Your internal reference number

string | null
is_test
required
Is Test

Whether this shipment was created with a test API key

boolean
ioss_registered
Ioss Registered

Per-shipment EU IOSS registration. Null when the brand default was used.

boolean | null
currency
required
Currency

Shipment currency (ISO 4217)

string
total_duties
required
Total Duties

Total duty amount across all items

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
total_taxes
required
Total Taxes

Total tax amount across all items

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
total_additional_country_charges
required
Total Additional Country Charges

Destination-country surcharges imposed in addition to duties and taxes

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
total_additional_fees
required
Total Additional Fees

Total additional fees

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
total_amount
required
Total Amount

Grand total: duties + taxes + additional country charges + additional fees

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
payment_status
required

Current payment status (pending, paid, expired, etc.)

string
Allowed values: PENDING PAID FAILED EXPIRED EXEMPT REFUNDED
created
required
Created

Shipment creation timestamp (UTC)

string format: date-time
items
required
Items

Line items with duty/tax breakdown

Array<object>
object
description
required
Description

Original item description as submitted

string | null
description_resolved
required
Description Resolved

Resolved item description after customs classification

string | null
hs_code
required
Hs Code

HS code as submitted

string | null
hs_code_resolved
required
Hs Code Resolved

HS code resolved by Duty Pro for the destination country

string | null
hs_code_resolved_import
required
Hs Code Resolved Import

Resolved import HS code for the destination country

string | null
hs_code_resolved_export
required
Hs Code Resolved Export

Resolved export HS code for the origin country

string | null
country_of_origin
required
Country Of Origin

Country of origin (ISO 3166-1 alpha-2)

string
declared_value
required
Declared Value

Declared value per unit

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
quantity
required
Quantity

Number of units

integer
total_value
required
Total Value

Total value for all units

string | null
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
shipping_cost
required
Shipping Cost

Shipping cost for this line item, regardless of quantity

string | null
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
duty_amount
required
Duty Amount

Calculated duty amount for this item

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
tax_amount
required
Tax Amount

Calculated tax amount for this item

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
fees
required
Fees

Additional fees applied to the shipment

Array<object>
object
fee_type
required
Fee Type

Fee type identifier

string
display_name
required
Display Name

Human-readable fee name shown to the consignee

string
amount
required
Amount

Fee amount in the shipment currency

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
original_amount
required
Original Amount

Fee amount in its original currency before conversion

string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
original_currency
required
Original Currency

Original currency of the fee before conversion

string
payment_link
required
Payment Link

URL for the consignee payment page. Null if no communication has been sent.

string | null
tracking_link
Tracking Link

Carrier tracking URL for the consignee. Null if neither a shipment override nor a brand/organization template is configured.

string | null

Validation Error

object
detail
Detail
Array<object>
object
loc
required
Location
Array<string | integer>
msg
required
Message
string
type
required
Error Type
string