# CSV import via FTP
URL: https://support.starshipit.com/articles/115001655223-csv-import-via-ftp
Canonical: https://support.starshipit.com/articles/115001655223-csv-import-via-ftp
Markdown: https://support.starshipit.com/articles/115001655223-csv-import-via-ftp.md
Updated: 2026-11-05

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Connect an FTP or SFTP server to import CSV orders, test file access and receive tracking information after printing.

Connect your FTP or SFTP server to import orders from CSV files and receive tracking information after printing. Use this when your platform can exchange CSV files but does not have a direct Starshipit integration.

## Before you begin

- Set up your [CSV file template](/articles/204503255-csv-file-integration) and verify it with a manual import before enabling automatic imports.
- Ask your server administrator for the protocol, host, port, username, password and base directory path.
- Confirm the account can list directories, create the required folders, and upload, download, move and delete files within that directory. The connection test performs these operations using a test file.
- If your server restricts incoming connections, agree the firewall requirements in [Check network access](#check-network-access) before testing.

## Connect your server

1. In Starshipit, go to **Settings > Integrations > Add a new integration > CSV FTP**. In UI 2.0, you can open **[CSV FTP](https://next.starshipit.com/settings/integrations/csv-ftp)** directly.
2. Tick **Enable CSV FTP**.
3. Under **Protocol**, select **FTP** or **SFTP** to match your server.
4. Enter the connection details below for the selected protocol.
5. For FTP, set the data connection and encryption options described in [Choose FTP connection options](#choose-ftp-connection-options).
6. Click **Save**.
7. Reopen the settings and check the selected protocol, host, port and directory path.

| Field | What to enter |
| --- | --- |
| **Host** | The server hostname or IP address supplied by your server administrator. |
| **Port** | The server's configured port. The form starts with `21` for FTP and `22` for SFTP; use a different port if your administrator specifies one. |
| **Username** and **Password** | The credentials for the server account with access to the selected directory. Keep the password private. |
| **Directory path** | The base directory under which Starshipit uses `IN`, `OUT` and `HISTORY`. Confirm the path as seen by this server account. |

## Choose FTP connection options

These options appear for FTP. SFTP uses SSH and does not use the FTP data connection or SSL/TLS checkboxes.

| Option | How to choose |
| --- | --- |
| **Data connection type** | **Auto (default)** uses automatic passive negotiation. Select **Passive** or **Active** only to match your server administrator's requirements. |
| **Use SSL** | Enable this when your FTP server requires FTPS encryption. With **Implicit FTP over TLS** off, Starshipit uses explicit TLS. |
| **Implicit FTP over TLS** | Enable this together with **Use SSL** only when the server requires implicit FTPS. Confirm the port with your administrator; selecting this option does not change the port for you. |

## Check network access

Starshipit connects to your server to import orders and write back tracking. A successful connection from your own computer does not confirm that the server allows connections from Starshipit.

Ask your server administrator to confirm the following TCP ports and firewall rules. FTPS is FTP secured with TLS; SFTP is a separate protocol that uses SSH. Always use the server's configured port, even when it differs from the usual value below.

| Protocol | Connection port on your server | File-transfer access |
| --- | --- | --- |
| FTP or explicit FTPS | Usually `21`. | In passive mode, also allow connections from Starshipit to the server's configured passive data-port range. |
| Implicit FTPS | Usually `990`; enter the confirmed port in **Port**. | In passive mode, also allow the server's configured passive data-port range. |
| SFTP | Usually `22`. | File operations use the SSH connection; FTP data ports are not needed. |

For passive FTP or FTPS, check that the address advertised by the server is reachable when it is behind a firewall or NAT. Active FTP instead requires the server to open a data connection back to Starshipit; confirm compatibility with Starshipit Support and your server administrator before selecting it.

If the server requires a list of permitted client IP addresses, [contact Starshipit support](/ticket) to confirm the current source addresses for CSV FTP connection tests, automatic imports and tracking writeback. The [API and web access IP list](/articles/360000516376-list-of-ip-addresses-that-require-access-to-your-platform) covers other traffic; do not assume its API address or ports `80` and `443` cover FTP/SFTP.

## Test the connection

1. Select **Test to ensure it works** after saving.
2. Read the complete result. Confirm that directory access and the upload, download, move and delete checks succeed. A connection to the host alone does not verify file access.
3. Ask your server administrator to confirm that `IN`, `OUT` and `HISTORY` exist under the configured base directory. Starshipit attempts to create missing folders during the test; if they are created manually, use those exact uppercase names.

The test writes `TEST-CONNECTION.txt`, moves it from `OUT` to `HISTORY`, then attempts to delete it. It may create missing folders, so use the directory agreed with your server administrator.

## Verify imports and tracking writeback

| Folder | What it contains |
| --- | --- |
| `IN` | CSV files waiting to be imported. Successfully processed files move to `HISTORY`. |
| `HISTORY` | CSV files that have been processed. |
| `OUT` | Tracking information written after printing, with one file per order containing the customer name, order number, courier, tracking number and tracking URL. |

1. Place one intended CSV file using your verified template in `IN`.
2. Confirm the expected orders appear in Starshipit and the processed file moves to `HISTORY`.
3. When you are ready to ship an imported order, print its label and check the corresponding tracking file in `OUT`.

A successful connection test does not validate your CSV mappings or prove that a later import or tracking writeback has completed.

## Troubleshooting

### The connection test fails

Check the selected protocol, host and port first. Confirm the credentials and base directory with your server administrator, then check the FTP data connection and SSL/TLS settings if applicable. Keep the server's required security settings in place while investigating.

Ask the administrator to compare the attempt with the server's authentication, file-access and firewall logs. Note whether the failure occurs before login, during directory listing, or during a file operation.

If you need Support to investigate, provide:

- The exact test result, with passwords, tokens and unrelated private data removed.
- The attempt date and time, including time zone.
- The selected protocol, host, port and base directory, shared privately through Support.
- For FTP, the selected data connection type and SSL/TLS options.
- Whether the failure occurred during the connection test, an automatic import or tracking writeback.
- The relevant server/firewall log result, including the observed source IP and blocked destination port when available.

Do not send passwords or secret keys in screenshots or messages.

### The test passes but orders or tracking files are missing

Check each operation in the test result, the uppercase folder names and the server account's permissions. For missing orders, verify the CSV against your saved template and check whether its file remains in `IN`. For missing tracking files, confirm that the imported order's label was printed and that the server account can write to `OUT`.
