Start Shipment Import via JSON

POST /api/v1/shipments/imports

Maximum items: You can import up to 300 items per batch. For larger datasets, please split them into multiple batches.

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