Start Shipment Import via File

POST /api/v1/shipments/imports/file

Supported formats: CSV, XLS, XLSX
Minimum rows: Your file must contain at least two rows (one header row and one data row).
Maximum rows: You can import up to 300 rows per file. For larger datasets, please split them into multiple files.
Header requirements: Headers are case-sensitive and must match the defined format exactly.

File Headers

Header (Case sensitive)	Required	Example	Description
`tracking_number`	✅	DFSU7162007	The B/L, booking, or container number.
`tracking_type`	✅	container	The type of number being tracked. Choices are bill_of_lading, booking, container, and without_tracking.
`carrier`	❌	MSCU	The SCAC code for the shipping line. Recommended for container tracking to bypass auto-detection. This field is required for the tracking type: bl and bk
`reference`	❌	ABC345678	A client-generated unique identifier for the shipment. This field is required for creating 'without tracking' shipments.
`name`	❌		Your desired name for this shipment. If the shipment already exists, its name will be updated.
`viewers`	❌	[email protected], [email protected]	List of comma-separated emails to share this shipment with (as viewers).
`tags`	❌	Goods, Import	List of comma-separated strings to use as a tag for each shipment. Behaviour for setting tags is get or create, so if the tag does not exist, we create it. (case Insensitive).
`assignees`	❌	[email protected], [email protected]	A list of comma-separated emails to assign them to this shipment. Each email should be a member of the workspace; otherwise, it will be ignored.
`cf\_{custom_field_slug}`	❌	PO#111	Your custom fields for this shipment with this format: cf_<custom_field_slug>. Custom field slugs are available on the custom fields settings page in the dashboard.
`origin_country_code`	❌	GB
`destination_country_code`	❌	US

Reference:

Allowed characters: A-Z a-z 0-9 . _ - / and space
Length: 1-255 characters
Whitespace: Leading and trailing spaces are trimmed and internal spaces are preserved
Case: Stored as provided (case-preserving) and matching is case-insensitive

Errors

Code	`TRACKING_NUMBER_REQUIRED`
Message	The tracking_number field cannot be empty.
Suggested Fix	Please provide a valid tracking number for this shipment.
Target	`tracking_number`

Code	`REFERENCE_INVALID_FORMAT`
Message	The reference 'example' contains invalid characters.
Suggested Fix	Please use only letters (a-Z), numbers (0-9), and the special characters: -, _, /.
Target	`reference`

Code	`CARRIER_INVALID_FORMAT`
Message	The carrier 'invalid' has an invalid format. Expected a string.
Suggested Fix	A SCAC must be exactly 4 alphanumeric characters (e.g., 'MSCU'). Use 'AUTO' for automatic carrier detection.
Target	`carrier`

Code	`CARRIER_NOT_SUPPORTED`
Message	The carrier with SCAC 'INVALID' is not currently supported.
Suggested Fix	Please check our list of supported carriers. If you'd like us to support this carrier, please contact our team.
Target	`carrier_scac`

Code	`NAME_TOO_LONG`
Message	The name field for this shipment is too long. The maximum allowed length is 255 characters.
Suggested Fix	Please shorten the shipment name to 255 characters or fewer.
Target	`name`

Code	`REFERENCE_REQUIRED`
Message	Reference is required for this tracking_type
Suggested Fix	Please provide a reference for this shipment.
Target	`reference`

Code	`TRACKING_TYPE_INVALID`
Message	The tracking type 'invalid_type' is invalid.
Suggested Fix	Please provide a valid tracking type for this shipment. Choices are : container, bill_of_lading, booking, and order.
Target	`tracking_type`

Code	`TRACKING_NUMBER_INVALID`
Message	The tracking number 'invalid_number' is invalid.
Suggested Fix	Please provide a valid tracking number for this shipment.
Target	`tracking_number`

Code	`AUTO_NOT_APPLICABLE`
Message	AUTO is not applicable for bill_of_lading.
Suggested Fix	Please provide a valid carrier SCAC code.
Target	`carrier_scac`

Code	`CARRIER_SCAC_REQUIRED`
Message	Carrier SCAC is required for bill_of_lading.
Suggested Fix	Please provide a valid carrier SCAC code.
Target	`carrier_scac`

Code	`TAG_NAME_TOO_LONG`
Message	The tag name 'very_long_tag_name_that_exceeds_limit' is too long.
Suggested Fix	Please shorten the tag name to 128 characters or fewer.
Target	`tags`

Code	`REFERENCE_DUPLICATE_IN_BATCH`
Message	The reference 'duplicate_ref' is used for more than one shipment in this import file.
Suggested Fix	Each shipment within a single import file must have a unique reference.
Target	`reference`

Code	`REFERENCE_ALREADY_EXISTS`
Message	The reference 'existing_ref' is already in use by another shipment in your workspace.
Suggested Fix	To update an existing shipment, ensure the tracking number and carrier match. To create a new shipment, please use a new, unique reference.
Target	`reference`

Code	`SHIPMENT_DUPLICATE_IN_BATCH`
Message	The combination of tracking number 'tracking123' and carrier 'MSCU' appears multiple times in this import file.
Suggested Fix	Please remove the duplicate shipment entry from your import file.
Target	`tracking_request`

Warnings

Warning Code	`CUSTOM_FIELD_INVALID_TYPE`
Message	The value for the custom field 'field_slug' has the wrong type. Expected a 'string'
Suggested Fix	Please ensure the value matches the data type defined for this custom field (e.g., Number, Date, Text).
Target	`custom_fields`

Warning Code	`CUSTOM_FIELD_TOO_LONG`
Message	The value for the custom field 'field_slug' is too long.
Suggested Fix	Please shorten the value for the custom field '{field_slug}'.
Target	`custom_fields`

Warning Code	`CUSTOM_FIELD_IGNORED_UNKNOWN`
Message	The shipment was processed, but the custom field 'unknown_field' was ignored because it is not defined in your workspace.
Suggested Fix	To include this data, please create the custom field in your workspace settings and then update this shipment.
Target	`custom_fields`

Warning Code	`EMAIL_IGNORED_INVALID_FORMAT`
Message	The shipment was processed, but the email address 'invalid_email' was ignored because it has an invalid format.
Suggested Fix	Please check the email address for typos. You can re-share or re-assign the shipment from the dashboard.
Target	`shared_with, assignees`

Warning Code	`SHARING_IGNORED_INCORRECT_ROLE`
Message	The shipment was processed, but it could not be shared with 'invalid_email' because their account does not have permissions to view shipments.
Suggested Fix	Please ensure you are sharing with users who have 'viewer' permissions, or contact your workspace administrator to adjust the user's role.
Target	`shared_with`

Request

Accepted