The FTP Fulfillment Channel connector integrates Pipe17 with third-party logistics providers (3PLs) and warehouses that do not expose a REST API. Instead of HTTP calls, all communication happens through files on an FTP server - the connector uploads outbound files for the 3PL to consume and downloads inbound files that the 3PL places there.
This connector is designed for warehouses that manage operations through CSV, XML, or JSON files (sometimes via Excel or manual uploads), where direct API integration is not available or practical.
You can find the sample files at the bottom of this article.
Connector type: Logistics (3PL fulfillment channel) Supported protocols: FTP, FTPS, SFTP
How It Works
Architecture
All data exchange is file-based:
- Pipe17 → 3PL (outbound): Pipe17 generates a file (CSV, XML, or JSON) and uploads it to a designated folder on the FTP server. The warehouse monitors that folder and acts on the file.
- 3PL → Pipe17 (inbound): The warehouse creates a file and places it in a designated folder on the FTP server. The connector polls that folder, downloads new files, parses them, and creates or updates records in Pipe17.
File Lifecycle
Once the connector downloads an inbound file, it applies the action configured in Post-processing (the fileCompletion setting):
| Action | What happens |
|---|---|
| Move to ./processed folder (default) | The file is moved to a processed/ subfolder within the same path, e.g. in/fulfillments/processed/
|
| Remove file | The file is deleted from the FTP server immediately after processing |
Note: Pipe17 downloads and stores the file internally before processing. Even if the 3PL deletes files from their server on their own schedule, data is not lost.
Data Format
The connector converts between the 3PL's file format and Pipe17's internal JSON representation on every transfer. The file format is set once at the connection level and applies to all flows.
Setup and Settings
Step 1: Prerequisites for the FTP Server
Before connecting, the FTP server administrator must:
- Create the required folders for every flow you plan to enable. The connector will not create folders automatically. If a configured path does not exist, uploads will fail. Default paths are listed per flow in the Settings section below.
- Provide credentials with read and write access to those folders.
Step 2: Connection Settings
Navigate to Integrations → Add integration → FTP Fulfillment channel.
These settings apply globally to all flows on the connection.
| Setting | Description | Default |
|---|---|---|
| Connection protocol | FTP, FTPS, or SFTP | FTP |
| Host | Hostname or IP address of the FTP server | (required) |
| Port | Port number | 22 |
| Username | FTP account login | (required) |
| Password | FTP account password | (required) |
| Import/export file type | The file format used for all flows on this connection - see File Formats section below | JSON |
| Post-processing action | What to do with inbound files after they are processed: move to ./processed folder, or remove the file |
Move to ./processed |
| CSV delimiter | Column delimiter when using a CSV file format | Comma (,) |
| Case-insensitive CSV fields | When enabled, field name matching in inbound CSV files ignores case | Off |
File Formats
| Format | Best for |
|---|---|
| JSON | API-style integrations; structured nested data |
| CSV (flatten) | Flat tabular files; nested arrays use dot-path notation (e.g. lineItems.0.sku) |
| CSV (unwind) | Tabular files where each array item (e.g. each line item) becomes its own row |
| CSV (Extron) | Warehouses using the Extron 3PL platform format |
| CSV (Aspen) | Warehouses using the Aspen 3PL platform format |
| XML | Standard XML with entity-typed root elements |
| XML (SantaFe 3PL) | Warehouses on the SantaFe 3PL platform |
Step 3: Flow Settings
Enable only the flows your 3PL requires. Each flow has a toggle and path settings described in the Flows section below.
Flows
1. Shipping Requests - Pipe17 → FTP
When an order is ready to be fulfilled, Pipe17 generates a shipping request file and pushes it to the 3PL's FTP server.
Direction: Outbound (Pipe17 uploads)
| Setting | Description | Default |
|---|---|---|
| Push shipping requests to FTP | Enable/disable this flow | Off |
| Upload path | FTP directory where shipping request files are placed | out/shipments |
| File name components | Parts included in the generated filename. Choose any combination of: Timestamp, Order ID, Entity Type (shipments) |
Timestamp + Order ID |
Filename example: shipments-20240315093000-ORD-1234.csv
The 3PL monitors this folder, retrieves the file, and processes the outbound shipment.
2. Fulfillments - FTP → Pipe17
After the 3PL ships an order, they place a fulfillment (shipment confirmation) file on the FTP server. The connector downloads it and creates a fulfillment record in Pipe17, completing the order.
Direction: Inbound (connector downloads)
| Setting | Description | Default |
|---|---|---|
| Pull fulfillments from FTP | Enable/disable this flow | Off |
| Download path | FTP directory the connector monitors for fulfillment files | in/fulfillments |
A fulfillment file should include at a minimum: SKU, quantity, tracking number, and the external order ID to match back to the original order.
3. Inventory - FTP → Pipe17
The 3PL periodically places inventory snapshot files on the FTP server. The connector pulls these and updates inventory levels in Pipe17.
Direction: Inbound (connector downloads)
| Setting | Description | Default |
|---|---|---|
| Pull inventory from FTP | Enable/disable this flow | Off |
| Download path | FTP directory the connector monitors | in/inventory |
| SKU filter | Process only inventory for specific SKUs. Leave empty to process all | (empty - all SKUs) |
An inventory file should include at a minimum: SKU, location ID, and available/on-hand quantities.
4. Locations - FTP → Pipe17
The connector can pull warehouse location definitions from FTP and register them in Pipe17, so that subsequent flows (especially arrivals) can route to the correct location.
Direction: Inbound (connector downloads)
| Setting | Description | Default |
|---|---|---|
| Pull locations from FTP | Enable/disable this flow | Off |
| Location mode | Choose how locations are sourced: create a single default location only; pull locations from FTP; or both | Create default location only |
| Download path | FTP directory to pull location files from | in/locations |
For simpler integrations with a single warehouse, set location mode to Create default location only - no FTP path is needed.
5. Products - Pipe17 → FTP
Pipe17 pushes the product catalog to the 3PL's FTP server so the warehouse has up-to-date SKU and product information.
Direction: Outbound (Pipe17 uploads)
| Setting | Description | Default |
|---|---|---|
| Push products to FTP | Enable/disable this flow | Off |
| Upload path | FTP directory where product files are placed | out/products |
| File name components | Parts included in the generated filename: Timestamp, SKU, Entity Type (products) |
Timestamp |
| SKU filter | Push only products with these SKUs. Leave empty for the full catalog | (empty - all SKUs) |
| Force products catalog resync | Trigger a one-time full catalog push | Off |
6. Purchase Order / Transfer Order Arrivals - Pipe17 → FTP
Note: The PO/TO workflow (arrivals and receipts) is part of FTP connector v2. This section describes the intended behavior based on the connector roadmap. Confirm availability with your Pipe17 account team before configuring.
Background: POs, TOs, and Arrivals
Pipe17 supports two types of inbound goods movements:
| Type | What it is | Direction |
|---|---|---|
| Purchase Order (PO) | Goods arriving from an external supplier | Supplier → Warehouse |
| Transfer Order (TO) | Goods moving between two of your own warehouses | Warehouse A → Warehouse B |
Both are represented as arrivals in Pipe17. An arrival is an advance notice to the warehouse that goods are coming. When those goods physically arrive, the warehouse creates a receipt confirming what was actually received.
Arrivals-Out (ASN): Pipe17 → FTP
When an arrival is created in Pipe17 (from a PO or TO), the connector uploads an ASN (Advanced Shipping Notice) file to the FTP server to notify the 3PL.
Direction: Outbound (connector uploads)
| Setting | Description | Default |
|---|---|---|
| Enable arrivals-out | Enable/disable this flow | Off |
| Upload path | FTP directory where arrival files are placed | out/arrivals |
| File name pattern | Template for generated filenames. Available tokens: {extArrivalId}, {arrivalId}, {timestamp}
|
{extArrivalId}_{timestamp} |
Example filename: PO-2026-001_20240315093000.csv
After the file is uploaded, Pipe17 updates the arrival status from shipped to expected (meaning the 3PL has been notified).
Receipts-In: FTP → Pipe17
After physical goods arrive at the warehouse, the 3PL creates a receipt file and places it on the FTP server. The connector downloads it and creates a receipt record in Pipe17.
Direction: Inbound (connector downloads)
| Setting | Description | Default |
|---|---|---|
| Enable receipts-in | Enable/disable this flow | Off |
| Download path | FTP directory the connector monitors | in/receipts |
| File pattern | Glob pattern to match incoming receipt files (e.g. RECEIPT_*.csv) |
(all files in path) |
A receipt file must include at minimum: arrival ID (or external arrival ID) to link back to the correct PO/TO, SKU, and quantity received.
Receipts can arrive incrementally - if one truck delivers part of the PO today and the rest next week, each delivery generates a separate receipt file. Pipe17 aggregates them against the same arrival and moves the status through:
[ shipped ] → [ expected ] → [ partialReceived ] → [ received ]
If goods are cancelled, the arrival moves to cancelled and no further processing occurs.
Location Filtering for Arrivals
If you have multiple warehouses but only one uses this FTP connector, configure a location filter to restrict the arrivals-out flow to only the relevant Pipe17 location IDs. Arrivals destined for other locations are skipped.
Custom Field Mapping
Each flow supports custom field mapping to accommodate the 3PL's specific file format. The connector ships with default mappings for standard fields (SKU, quantity, tracking number, etc.), but you can extend these to pass additional fields through.
For example, if the 3PL expects a supplier_ref column that maps to an order's custom field, you add that mapping in the flow's JSON mapping configuration.
Mapping uses the same dot-path notation as the file format. For CSV (flatten), nested fields use index notation: lineItems.0.sku. For CSV (unwind), each row represents one line item so fields are flat.
Troubleshooting
| Area | Check | What to do |
|---|---|---|
| Upload fails: path not found | Target FTP folder does not exist | Ask the FTP administrator to create the required folder (e.g., out/shipments, out/arrivals). The connector does not create directories. Verify any custom paths configured in settings also exist |
| Inbound files not being picked up | Wrong path | Confirm the configured download path exactly matches the 3PL file location, including case sensitivity |
| File pattern mismatch | Ensure the configured file pattern (e.g., RECEIPT_*.csv) matches actual filenames from the 3PL |
|
| Flow not enabled | Verify the relevant flow (e.g., fulfillments.in, inventory.in) is enabled |
|
| Files already processed | If fileCompletion is set to Move to processed, check the processed/ folder for previously handled files |
|
| Duplicate records being created | Files reprocessed multiple times | Set fileCompletion to Move to processed folder or Remove file so each file is processed once. Confirm the 3PL is not re-uploading files with the same name |
| Receipts not matching arrivals | Arrival ID mismatch (extArrivalId) |
Ensure the 3PL uses the exact arrival ID from the original file. The value is case-sensitive. Verify against the arrival record in the app |
| CSV field mapping errors | Header case mismatch | Enable Case-insensitive CSV fields if header casing varies (e.g., SKU vs sku) |
| Wrong delimiter | Update the CSV delimiter setting to match the file format (comma, semicolon, tab) | |
| Incorrect CSV format | Switch between CSV (flatten) and CSV (unwind) based on the file structure (indexed vs one-row-per-item) | |
| SFTP server compatibility issues | Limited SFTP support (ROM or database-backed servers) | Use Remove file instead of Move to processed, or work with the 3PL to use a standards-compliant SFTP server. Contact support if issues continue |
Need Help?
If you need additional assistance:
- Use Ask Pippen, our AI agent, located at the top of the app page.
- Submit a support request with as much relevant detail as possible. Learn how to submit a request.
- For urgent issues, email us directly at support@pipe17.com.
We're here to help you succeed with your operations.
Comments
0 comments