Skip to main content
Available to all Perform.AI customers. Users with the Administrator or Parcel Creation role can upload shipments.

​
Summary

File Upload creates shipments and orders in Perform.AI from a CSV file, either dropped into Shipment Overview in the portal or placed in an SFTP folder that Perform.AI processes on a schedule. Every processed file comes back as a status report that tells you, row by row, what was accepted, rejected or accepted with warnings.

​
Who it’s for

Operations and customer service teams who need to get shipments into Perform.AI without an API integration: a daily export from a warehouse system, a one-off backfill, or a handful of parcels added by hand.

​
Key benefits

  • Bulk creation without code. Export shipments from your own system into the Perform.AI CSV template and upload the file. Each row becomes a shipment, with its order, events and documents if you include them.
  • Scheduled processing over SFTP. Drop files into your SFTP folder and Perform.AI pulls and processes them on a defined schedule. Perform.AI can parse your own file format and map its fields to the standard schema, so you do not have to change your export.
  • A status report for every file. Each upload produces a processed file report that mirrors your file and adds the outcome and the error or warning message for every row.
  • Single and multi-parcel entry for small volumes. Add one parcel with its details, or paste or scan a list of tracking numbers, directly in the portal.

​
How it works

​
Ways to create shipments in the portal

​
The CSV template

The template defines the fields a shipment, order, event or document can carry. Download it from Create Shipment Template in the upload dialog, or build your own file with the same column headers, then fill one row per shipment. You only need the columns you use, as long as the required ones are present and the values follow the validation rules in the field guide. Every row needs at least:
  • shipment[shipment_id]
  • shipment[tracking_number]
Always include the carrier reference, or select the carrier, when you create shipments. Perform.AI then assigns the carrier immediately and starts retrieving tracking events, instead of having to identify the carrier from the tracking number.

​
Validation rules that reject a row

​
SFTP upload

For recurring files, Perform.AI provides an SFTP or FTP folder. You drop files there and Perform.AI pulls and processes them on a defined schedule. The SFTP integration can parse your own file format and map its fields to the Perform.AI schema, so the file does not have to be in the portal template. Request SFTP access from your account team.

​
The File Upload Status Report

Each time a CSV file is processed, whether it came through SFTP or the portal, Perform.AI generates a processed file report and places it in the processed_file_report/ folder of your SFTP folder. The report mirrors your original file with two extra columns.

​
Set up in the portal

Go to Shipment Overview and select Add Parcels.
  1. Choose File Upload.
  2. Select Create Shipment Template to download the CSV template, or prepare your own file with the same column headers.
  3. Fill one row per shipment. Include at least shipment[shipment_id] and shipment[tracking_number], and the carrier reference.
  4. Save the file in CSV format.
  5. Drop the file into the upload box and select Confirm.
To add a single parcel instead, choose Create Single Parcel, enter the tracking number and carrier, add any additional details and select Add Parcel. To add several by tracking number, choose Create Multiple Parcels, enter one tracking number per line and select Add Parcels. Carriers must be configured in Settings > Carriers before you upload shipments that reference them. See Carrier Integration.

​
FAQ

​
Which fields are required?

At least shipment[shipment_id] and shipment[tracking_number]. Everything else is optional, but some fields need a companion: an order[order_reference] only works together with order[order_id].

​
Can I upload my own file format instead of the template?

In the portal, no: the file must use the template’s column headers. Over SFTP, yes: Perform.AI can parse your format and map it to its schema as part of setting up the SFTP integration.

​
Where do I see what went wrong with a row?

In the File Upload Status Report in the processed_file_report/ folder of your SFTP folder. The Errors/Warnings column names the problem for each rejected or warned row.

​
What is the difference between Rejected and Warning?

A Rejected row has at least one validation error and was not created. A Warning row was created, but something in it needs attention, such as a value that could not be used.

​
Do I need to set up carriers first?

Yes. A carrier_reference in the file must already exist under Settings > Carriers, otherwise the row is rejected.

​
Troubleshooting