Shipment File Transfers

Transfer historical data to improve training.

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.

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

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.

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.

  1. Gather your configuration details.
  • 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.
  • 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.
  • 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.
  1. 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.
  2. 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.
  3. 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 URL, Access Key ID, & Secret Keys - Will be provided directly to you upon completion of the setup request
  4. 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/[partner_name]/historical-shipment-data/
  5. 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.

🚧

Required field for customers not using Shipium label creation

If you are NOT using Shipium's label creation service, you must include a partner_reference_identifier in your shipment file, as noted in the 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. Two rows of sample values are included in each template; be sure to replace the sample data with your own.

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

File format

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.

# Column nameRequired/OptionalDescriptionType
1shipment_idRequiredThe unique identifier for the shipment that was shippedString
2shipium_shipment_idOptionalThe Shipium unique identifier for the shipment that was shippedString
3order_idRequiredThe customer order reference ID tied to one or more outbound shipmentsString
4package_idOptionalThe package identifier tied to one or more packages contained in a shipment (if applicable)String
5partner_reference_identifierConditionalYour organization's unique reference identifier for the shipment file; this is required if you are NOT using Shipium's service to create labels.String
6carrier_tracking_idRequiredThe carrier-assigned unique label tracking ID assigned at label creationString
7tenant_idOptionalThe unique identifier of the specific tenant account the shipment was executed on if one or more tenants are configured under your Shipium account setupUUID
8tenant_nameOptionalThe name of the specific tenant account the shipment was executed on if one or more tenants are configured under your Shipium account setupString
9label_costOptionalThe individual cost per label under a shipmentFloat
10currency_codeRequiredThe three-character standard currency code associated with the invoiced shipment costscurrency code
11ordered_date_timeOptionalThe order creation timestampISO 8601 date-time with offset
12ordered_date_time_timezoneOptionalThe order creation timestamp timezoneISO 8601 date-time with offset
13shipped_date_timeRequiredThe shipped timestamp when the package departed your origin facilityISO 8601 date-time with offset
14shipped_date_time_timezoneRequiredThe shipped timestamp timezone when the package departed your origin facilityISO 8601 date-time with offset
15delivered_at_date_timeRequiredThe delivery timestamp provided by the final mile carrier upon delivery of the packageISO 8601 date-time with offset
16delivered_at_date_time_timezoneRequiredThe delivery timestamp timezone provided by the final mile carrier upon delivery of the packageISO 8601 date-time with offset
17desired_delivery_dateOptionalThe original date requested for delivery of the customer orderISO 8601 date-time
18origin_idOptionalThe reference identifier for the ship-from location within your networkUUID
19origin_postal_codeRequiredPostal code from which the package was shippedString
20origin_state_regionOptionalState or region from which the package was shippedString
21origin_country_codeRequiredTwo-character country code from which the package was shippedISO 3166 country code
22destination_state_regionOptionalState or region to which the package was shippedString
23destination_postal_codeRequiredPostal code to which the package was shippedString
24destination_country_codeRequiredTwo-character country code to which the package was shippedISO 3166 country code
25destination_address_typeRequiredThe address type code for the location to which the package was shipped:
residential or commercial
String enumeration
26destination_is_po_boxRequiredBoolean indicating if the location to which the package was shipped was a post office box:
true or false
Boolean
27package_materialRequiredThe type of packaging material used:
box, envelope, flat_pack, mailing_tube, or parcel_pallet
String enumeration
28package_lengthRequiredThe longest side of the package in package_linear_unit unitsFloat
29package_widthRequiredThe second longest side of the package in package_linear_unit unitsFloat
30package_heightRequiredThe shortest side of the package in package_linear_unit unitsFloat
31package_linear_unitRequiredThe unit of linear measure for the package:
in or cm
String enumeration
32package_weightRequiredThe total weight of the package, including packaging and contents in package_weight_unit unitsFloat
33billable_weightOptionalThe invoiced weight from the carrierFloat
34package_weight_unitRequiredThe unit of weight measure for the package:
g, kg, oz, or lb
String enumeration
35carrier_idRequiredThe carrier identifier for the last mile carrier;
see Supported Carriers for listing
String enumeration
36carrier_service_method_idRequiredThe carrier service method identifier for the last mile carrier;
see Supported Carriers for listing
String enumeration
37delivery_signature_optionOptionalBoolean indicating if the package required an adult signature upon delivery:
true or false
Boolean
38ship_optionOptionalOptional parameter to indicate your preferred ship option; see Ship Options' for listingString
39contains_hazmatOptionalBoolean indicating if the package contained one or more hazardous materials items:
true or false
Boolean
40lithium_ionOptionalBoolean indicating if the package contained one or more items containing a lithium ion cell:
true or false
Boolean
41limited_quantityOptionalBoolean indicating if the package contained one or more limited quantity items
true, false
Boolean