Connecting FTP Fulfillment Channel to Pipe17

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):

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:

1. 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.
2. 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.

File Formats

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)

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)

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)

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)

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)

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:

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)

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)

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.

7. Returns - Pipe17 → FTP

When a customer return is on its way back to the warehouse, the app uploads a file to the 3PL's FTP server telling the warehouse which goods to expect. The warehouse uses the file to check off the return when it arrives.

Direction: Outbound (Pipe17 uploads)

A return is sent only when both of these are true:

• The return status is shipped. Returns at draft or authorized are not sent.
• The return is assigned to a location that belongs to this FTP integration. If no location is linked to the integration, no returns are sent.

The app checks for eligible returns every 5 minutes and uploads one file per return in the connection's file format. If your returns mapping sets the filename, it overrides the filename setting.

What happens to the return:

A failed status means the file could not be delivered to the server. That includes a server that was briefly unreachable, not only bad data. The app does not retry failed returns on its own.

8. Return Receipts - FTP → Pipe17

When the warehouse receives returned goods, it places a receipt confirmation file on the FTP server. The connector downloads the file and adds a receipt to the matching return in the app. The receipt records the SKUs and quantities received and the arrival date. It can also include damaged quantity and a batch identifier when the warehouse sends them.

Direction: Inbound (connector downloads)

Return receipts are separate from the arrival receipts in section 6, which apply to purchase orders and transfer orders. Each flow has its own settings and folder.

How a receipt is matched to a return:

• The app looks for the return using the return reference the warehouse sends back in the file. The order number is never used, because one order can have more than one return.
• The return must already exist in the app. The app never creates a return from a warehouse file. If no return matches, the record is skipped and the file is still processed.
• If the same confirmation is processed again, the app does not create a duplicate receipt.
• Ask your warehouse to send back the same return reference that was in the outbound returns file.

If Upload results for incoming files is turned on for the connection, the app writes a .results file for each processed file in a results subfolder of the download path. The file has one row per record, marked as processed, unresolved, duplicate or error. Check this file first when a receipt doesn't appear.

To process specific files again, for example after a mapping fix or when the warehouse re-sends a file, run the Pull return receipts from a file action on the integration. It processes the named files right away, works even when the flow is turned off, leaves the files on the server as they are, and does not create duplicate receipts.

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.

Returns and return receipts always need a custom mapping that matches your warehouse's file layout. The Pipe17 team builds this mapping during implementation. Turning on the returns settings without that mapping won't produce working files. To build it, the team needs sample files for both directions, the warehouse's file specification, any account codes the warehouse requires (such as a client or site code), and the field the warehouse uses as its receipt number. Column renaming through mappings.csv does not apply to the returns flows.

Troubleshooting

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.

We're here to help you succeed with your operations.