About Shipium historical shipment file transfers

Shipium offers a variety of options for you to transfer regular historical shipment data exports for Shipium ML model training. In addition, you can transfer exports for Carrier Selection webhook generation for labels generated outside the Shipium system; this is useful if you are a Carrier Selection customer but you do not generate labels with Shipium.

Before requesting a file transfer, you will first need to identify if you will be manually dropping files or configuring an automated process to handle file transfers on a set cadence.

Manual transfers

Shipium supports CSV bulk file uploads natively within the Shipium Console.
Alternatively, files can be submitted in a ticket using the Shipium Customer Help Center.

Automated transfers

Shipium supports both SFTP and S3 direct file drops.

If you would like to pursue setting up either a manual or automated file transfer, please reach out to your Shipium Implementation Team Member or Customer Success Manager to start the process. If you are a Carrier Selection customer but you don't generate labels with Shipium, the Carrier Selection without Label Generation document provides best practices for providing your shipment data.

The rest of this document provides a full onboarding guide and FAQs.

Set up automated file transfers for your organization

To start using an automated file transfer method, you will need to complete the following steps. Your dedicated Shipium team member will be available to assist you with each one.

Gather your configuration details.
1. For SFTP, you'll provide a username, public key, and IP address.
  1. Username. It is recommended to use a credential username associated with the service/application that will be accessing the Shipium hosted SFTP or S3 location.
  2. Public Key. Asymmetric encryption is used to secure file drops and will require your public key to enable us to decrypt files uploaded to the SFTP or S3. You'll use the ssh-keygen command to create your public keys (it's generally safer to generate key pairs locally on a trusted device). To create a proper public key, you'll need to adhere to these constraints:
    - No line breaks. The public key must be a single line without any line breaks.
    - Proper key type. The key should start with a valid key type, such as ssh-rsa, ssh-ed25519, and ecdsa-sha2-nistp256.
    - No trailing characters. There should be no trailing characters or new lines at the end of the key, and there should be no extra spaces before or after the key.
  3. IP Addresses. The IP(s) or range of IPs that will be used by your application to access a Shipium file share must be provided for Shipium to enable them on our IP allow-list.
2. For S3, you'll provide an Amazon Web Services (AWS) IAM role name and account ID.
  1. IAM role name. This is the user-defined name that uniquely identifies the IAM role within your AWS account.
  2. Account ID. This is a unique 12-digit identifier assigned to your AWS account.
Submit a customer setup request ticket.
Once you have successfully gathered all your internal configuration details, you can either directly support a setup request ticket via the Shipium Customer Help Center or send the configuration details directly to your dedicated Shipium team member for them to submit on your behalf.
Allow Shipium setup and processing.
Please allow 2-3 business days for Shipium to complete the processing of your file transfer setup request. Once completed, you will receive a ticket confirmation and/or email confirmation from your Shipium team member that your access has been successfully granted and available for immediate use.
Configure your SFTP or S3 connection.
Upon closure of your file transfer access request, you will immediately be able to access your secure drop location. Use the below details to complete your internal setup:
- For SFTP:
  Server Name - partner-upload.shipium.com
  Port - 22
- For S3:
  S3 Bucket - raw-partner-shipment-data-prod
Test the transfer.
Once you have completed the setup of your SFTP or S3 connection and confirm access, it is recommended to test the file handoffs using a test CSV file. This will allow Shipium to verify we are able to successfully decrypt and process the file transfer prior to automating the uploads.
- Folder Directory:
  Files uploaded to the SFTP or S3 must be placed in the pre-defined drop location that will default be available to you post setup.
  Drop Location - /[partner_name]/historical-shipment-data/
Schedule your uploads.
For customers not using Shipium label creation, we will require your historical shipment data to be uploaded at minimum once per month to ensure our ML models are kept up to date with the latest data regarding your network’s shipping performance to make the most accurate productions for you and your customers.
It is recommended to schedule these uploads to take place the first of each month to hand off the relevant historical shipping data for all shipments delivered within the prior month.

🚧
Important field requirement for Carrier Selection customers
If you are a Carrier Selection customer NOT using Shipium's label creation service, you must include a partner_reference_identifier in your shipment file, as noted in the Carrier Selection file format table below. This value is needed for Shipium to match your historical data with our Carrier Selection data.

Need Help? We are here to help! Let your Shipium team member know you are in need of assistance, and they will support you in troubleshooting.

Downloadable file templates

You can download a CSV template of the file format outlined below. Once you add your historical shipment data to the template, you can upload it via one of the mechanisms described above. Sample values are included in each template; be sure to replace the sample data with your own.

For Carrier Selection customers

Minimum required fields template. This CSV template includes only the minimum required fields needed.
All fields template. This CSV template includes all the required fields as well as the optional fields.

For Delivery Promise customers

Minimum required fields template. This CSV template includes only the minimum required fields needed.
All fields template. This CSV template includes all the required fields as well as the optional fields.

File format

The required fields vary depending on which Shipium product you're using. Use the table below that corresponds to your product.

For Carrier Selection customers

For the files that will be uploaded as part of this process, the following table shows the columns, the names that should appear in column headers, and a description of each of the fields. Fields that are required are highlighted in bold type.

	Request field	Required/Optional	Details
1	`shipment_id`	Required	Type: String Description: The unique identifier for the shipment that was shipped
2	`shipium_shipment_id`	Optional	Type: String Description: The Shipium unique identifier for the shipment that was shipped
3	`order_id`	Required	Type: String Description: The customer order reference ID tied to one or more outbound shipments
4	`package_id`	Optional	Type: String Description: The package identifier tied to one or more packages contained in a shipment (if applicable)
5	`partner_reference_identifier`	Conditional	Type: String Condition: Required for webhook generation Description: Your organization's unique reference identifier that matches the `partnerShipmentId` used in calls to Shipium's Carrier Selection APIs. This enables matching external shipments to carrier selections for webhook generation.
6	`carrier_tracking_id`	Required	Type: String Description: The carrier-assigned unique label tracking ID assigned at label creation
7	`tenant_id`	Optional	Type: UUID Description: The unique identifier of the specific tenant account the shipment was executed on if one or more tenants are configured under your Shipium account setup
8	`tenant_name`	Optional	Type: String Description: The name of the specific tenant account the shipment was executed on if one or more tenants are configured under your Shipium account setup
9	`label_cost`	Optional	Type: Float Description: The individual cost per label under a shipment
10	`currency_code`	Required	Type: String Description: The 2-character standard ISO 4217 currency code associated with the invoiced shipment costs
11	`ordered_date_time`	Optional	Type: String (date-time) Description: The order creation timestamp in ISO 8601 date-time format with offset
12	`ordered_date_time_timezone`	Optional	Type: String (date-time) Description: The order creation timestamp timezone in ISO 8601 date-time format with offset
13	`shipped_date_time`	Required	Type: String (date-time) Description: The shipped timestamp when the package departed your origin facility in ISO 8601 date-time format with offset
14	`shipped_date_time_timezone`	Required	Type: String (date-time) Description: The shipped timestamp timezone when the package departed your origin facility in ISO 8601 date-time format with offset
15	`delivered_at_date_time`	Required	Type: String (date-time) Description: The delivery timestamp provided by the final mile carrier upon delivery of the package in ISO 8601 date-time format with offset
16	`delivered_at_date_time_timezone`	Required	Type: String (date-time) Description: The delivery timestamp timezone provided by the final mile carrier upon delivery of the package in ISO 8601 date-time format with offset
17	`desired_delivery_date`	Optional	Type: String (date-time) Description: The original date requested for delivery of the customer order in ISO 8601 date-time format
18	`origin_id`	Optional	Type: UUID Description: The reference identifier for the ship-from location within your network
19	`origin_postal_code`	Required	Type: String Description: Postal code from which the package was shipped
20	`origin_state_region`	Optional	Type: String Description: State or region from which the package was shipped
21	`origin_country_code`	Required	Type: String (enumeration) Description: The 2-character ISO 3166-1 country code from which the package was shipped
22	`destination_state_region`	Optional	Type: String Description: State or region to which the package was shipped.
23	`destination_postal_code`	Required	Type: String Description: Postal code to which the package was shipped
24	`destination_country_code`	Required	Type: String (enumeration) Description: The 2-character ISO 3166-1 country code to which the package was shipped
25	`destination_address_type`	Required	Type: String (enumeration) Values: `residential`, `commercial` Description: The address type code for the location to which the package was shipped
26	`destination_is_po_box`	Required	Type: Boolean Values: `true` or `false` Description: Indicates if the location to which the package was shipped was a post office box
27	`package_material`	Required	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet` Description: The type of packaging material used
28	`package_length`	Required	Type: Float Description: The longest side of the package in `package_linear_unit` units
29	`package_width`	Required	Type: Float Description: The second longest side of the package in `package_linear_unit` units
30	`package_height`	Required	Type: Float Description: The shortest side of the package in `package_linear_unit` units
31	`package_linear_unit`	Required	Type: String (enumeration) Values: `in`, `cm` Description: The unit of linear measure for the package
32	`package_weight`	Required	Type: Float Description: The total weight of the package, including packaging and contents in `package_weight_unit` units
33	`billable_weight`	Optional	Type: Float Description: The invoiced weight from the carrier
34	`package_weight_unit`	Required	Type: String (enumeration) Values: `g`, `kg`, `oz`, `lb` Description: The unit of weight measure for the package
35	`carrier_id`	Required	Type: String (enumeration) Description: The carrier identifier for the last mile carrier; see Supported Carriers for listing.
36	`carrier_service_method_id`	Required	Type: String (enumeration) Description: The carrier service method identifier for the last mile carrier; see Supported Carriers for listing.
37	`delivery_signature_option`	Optional	Type: Boolean Values: `true` or `false` Description: Indicates if the package required an adult signature upon delivery
38	`ship_option`	Optional	Type: String Description: Optional parameter to indicate your preferred ship option; see Ship Options for listing.
39	`contains_hazmat`	Optional	Type: Boolean Values: `true` or `false` Description: Indicates if the package contained one or more hazardous materials items
40	`lithium_ion`	Optional	Type: Boolean Values: `true` or `false` Description: Indicates if the package contained one or more items containing a lithium ion cell
41	`limited_quantity`	Optional	Type: Boolean Values: `true` or `false` Description: Indicates if the package contained one or more limited quantity items

For Delivery Promise customers

	Request field	Required/Optional	Details
1	`shipment_id`	Required	Type: String Description: The unique identifier for the shipment
2	`order_id`	Optional	Type: String Description: The unique identifier for the order
3	`carrier_tracking_id`	Optional	Type: String Description: The tracking ID assigned by the carrier; used to troubleshoot poor data quality issues
4	`shipped_date_time`	Required	Type: String (date-time) Description: The date and time the package was shipped from your origin facility in ISO 8601 date-time format with offset
5	`shipped_date_time_timezone`	Required	Type: ISO 8601 date-time with offset Description: The timezone of the `shipped_date_time`; the format should be a valid timezone name, such as `America/Los_Angeles`.
6	`delivered_at_date_time`	Required	Type: String (date-time) Description: The delivery timestamp provided by the final mile carrier upon delivery of the package in ISO 8601 date-time format with offset
7	`delivered_at_date_time_timezone`	Required	Type: ISO 8601 date-time with offset Description: The timezone of the `delivered_at_date_time`; the format should be a valid timezone name, such as `America/Los_Angeles`.
8	`origin_postal_code`	Required	Type: String Description: Postal code from which the package was shipped
9	`origin_country_code`	Required	Type: String Description: The 2-character ISO 3166-1 country code from which the package was shipped
10	`destination_postal_code`	Required	Type: String Description: Postal code to which the package was shipped
11	`destination_country_code`	Required	Type: String Description: The 2-character ISO 3166-1 country code to which the package was shipped
12	`destination_address_type`	Optional	Type: String (enumeration) Values: `residential`, `commercial` Description: The address type code for the location to which the package was shipped
13	`destination_is_po_box`	Optional	Type: Boolean Values: `true` or `false` Description: Indicates if the location to which the package was shipped was a post office box
14	`carrier_id`	Required	Type: String (enumeration) Description: The Shipium carrier identifier for the carrier that was used to ship the package; see Supported Carriers for listing.
15	`carrier_service_method_id`	Required	Type: String (enumeration) Description: The Shipium carrier service method identifier that was used to ship the package; see Supported Carriers for listing.

Webhook generation for external labels (Carrier Selection only)

If your organization generates labels externally but uses Shipium's Carrier Selection service, historical shipment file transfers enable webhook notifications when your external labels are matched to carrier selections.

Requirements for webhook generation

Matching field. Include partner_reference_identifier that matches your partnerShipmentId from calls to Shipium's Carrier Selection APIs.
Processing SLA. Files are processed within 24 hours or by end of the following calendar day.
Age limit. You determine the timeframe for shipments that will generate webhooks.

How it works

You upload your historical shipment file via SFTP or S3.
Shipium processes and matches external shipments to carrier selections.
Matched shipments generate "label_imported" webhook events and display a status of "imported" in the Shipium Console.
Unmatched shipments are processed for ML training but don't generate webhooks.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: