> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # File Upload > Create shipments and orders in bulk from a CSV template in the portal or through an SFTP folder, with a status report per file, for operations teams. **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 | Option | What you enter | Notes | | - | - | - | | Create Single Parcel | Tracking number and carrier. Optionally order ID, name and email under **Add Additional Details**. | Press **Enter** or use a barcode scanner to add several parcels in a row, without the additional details. | | Create Multiple Parcels | A list of tracking numbers, one per **Enter**. | No additional details. | | File Upload | A CSV file in the Perform.AI template. | Bulk creation of shipments and orders with all supported fields. | ### 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]` > [!TIP] > > 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 | Rule | What fails | | - | - | | Required fields | A row without `shipment[shipment_id]` and `shipment[tracking_number]` is not created. | | Configured carrier | A `carrier_reference` that is not configured under **Settings** > **Carriers** is rejected. | | Accompanying fields | `order[order_reference]` without `order[order_id]`: both are needed to attach order information to a shipment. | | Unique values | `shipment[shipment_id]` must be unique per shipment. `documents[#][document_id]` must be unique within a shipment. | | Complete events | An event time and location without an event description or event key is incomplete and is not logged. | | Formats and limits | Date and time values must follow the format in the field guide. Fields with a maximum length reject longer values. | ### 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. | Column | Values | | - | - | | Processed Status | **Accepted**: the row was processed with no errors or warnings. **Rejected**: the row has at least one validation error and was not processed. **Warning**: the row was processed but has at least one validation warning and no errors. | | Errors/Warnings | The message for each row, such as a missing field or an incorrect format, so you can correct the row and upload it again. | ## 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](https://developers.perform.ai/products/platform/carrier-integration.md). ## 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 | Symptom | Cause | Fix | | - | - | - | | Rows are rejected with a missing field error | `shipment[shipment_id]` or `shipment[tracking_number]` is empty | Fill both columns for every row and upload again. | | Rows with a carrier are rejected | The `carrier_reference` is not configured in your account | Add the carrier and reference under **Settings** > **Carriers**, then re-upload. | | Order information is missing on created shipments | `order[order_reference]` was given without `order[order_id]` | Add the `order[order_id]` column and re-upload the affected rows. | | Duplicate error on upload | The same `shipment[shipment_id]` appears twice, or two documents in one shipment share a `document_id` | Make each shipment ID unique in the file and each document ID unique within a shipment. | | Events are missing from a shipment | The event row had a time and location but no description or event key | Add an event description or event key to every event. | | Date values are rejected | The date or time format does not match the field guide | Use the format defined in the template field guide and re-upload. | ## Related * [Shipment Overview](https://developers.perform.ai/products/post-purchase/shipment-overview.md) * [Carrier Integration](https://developers.perform.ai/products/platform/carrier-integration.md) * [Data Integration](https://developers.perform.ai/products/platform/data-integration.md) * [Integrations overview](https://developers.perform.ai/products/integrations/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.