SFTP Sales Channel Integration

Connect Neuro to your SFTP server and move data in and out with simple, structured file drops. This channel is ideal if you already work with SFTP, prefer files over APIs, or need a predictable, auditable way to exchange data.

At a Glance

What you can sync

• Orders

• Products

• Inventory

• Fulfilments

How it works

• Drop CSV or XML files into agreed folders on your SFTP server

• Neuro picks them up on a schedule, processes them and logs the results

• Processed files are moved into processed/ folders, with timestamped filenames

• Optional auto‑cleanup keeps your storage tidy

1. Key Features and Why They Matter

Multi-file, multi-format support

• Four data types: Orders, Products, Inventory and Fulfilments

• Two formats: CSV or XML per channel

Why it matters:

You can plug Neuro into existing feeds without redesigning your file format or creating an API integration.

Automatic, secure processing

• Automatic processing: Files are picked up and processed on a schedule

• Secure transfer: All data moves over SFTP with username/password authentication

Why it matters:

Your team keeps using familiar tools and folders while Neuro quietly keeps data in sync in the background.

Flexible CSV column mapping

• Map Neuro fields (for example order_id, customer_name) to your own header names

• Configure mappings separately for Orders, Fulfilments, Products and Inventory

• Any unmapped fields fall back to default system names

Why it matters:

You don’t need to rename your exports. Neuro adapts to your existing file layouts, which reduces friction and avoids mistakes.

Guided XML field mapping

• Visual XML builder with a step‑by‑step wizard

• Upload a sample XML and let Neuro analyse the structure

• Pick the record element (for example or )

• Map system fields to XML elements or attributes (including namespaces)

Why it matters:

You get the flexibility of custom XML without having to be an XML expert. The wizard makes complex structures manageable and repeatable.

Folder mappings that fit your structure

• Default folders are created automatically under your Base Path:

  • orders/ → orders/processed/

  • products/ → products/processed/

  • inventory/ → inventory/processed/

  • fulfilments/ → fulfilments/processed/

• Use Folder Mappings to point each data type to your own folders, such as incoming/orders/new or exports/shipments

Why it matters:

You can keep your existing SFTP layout and simply tell Neuro where to look, instead of reorganising your folders around the integration.

File tracking and auto‑cleanup

• Processed files are moved into a processed/ subfolder and timestamped

• Optional Auto Cleanup deletes processed files after a set number of days, per folder

• Default cleanup entries are created for orders/processed and products/processed (7 days)

Why it matters:

You keep a clear audit trail of what was processed, while avoiding a build‑up of old files that can complicate operations and compliance.

Error logging and visibility

• All processing errors are logged in channel transactions

• You can see which file failed, why, and at what time

Why it matters:

When something goes wrong, you can quickly trace the issue to a specific file, fix it, and re‑run without guesswork.

2. Set Up the SFTP Channel

2.1 Basic configuration

When you add an SFTP channel in Neuro, you will be asked for:

Make sure the SFTP user has read and write access to the base path and all relevant subfolders.

2.2 Choose your file format

Each SFTP channel works in either CSV or XML:

CSV

• Comma‑separated values with headers in the first row

• Ideal if you already export spreadsheets or CSV reports

XML

• Fully structured XML with a configurable layout

• Ideal if you work with more complex hierarchies or existing XML feeds

Changing the file format after the channel is created will reset all mappings. Neuro will ask you to confirm before doing this.

2.3 Default directory structure

On first connect, Neuro creates a set of default folders under your base path:

├── orders/ 
│ └── processed/ 
├── products/ 
│ └── processed/ 
├── inventory/ 
│ └── processed/ 
└── fulfilments/ 
  └── processed/ 

You can then use Folder Mappings to align these with your own structure. Neuro creates processed/ subfolders automatically under whichever paths you configure.

2.4 Folder mappings

To point Neuro at the right folders:

1. Open your SFTP channel settings in Neuro.

2. Scroll to Folder Mappings.

3. For each data type, you’ll see:

   • System Folder – Neuro’s default name (for example orders)

   • FTP Folder – The path on your SFTP server (for example incoming/orders/new)

4. Enter paths relative to your base path.

5. Click Save Folder Mapping.

Example mappings

Neuro will use the new locations from the next sync cycle.

2.5 CSV column mapping

If your channel uses CSV:

1. Save your SFTP connection details.

2. Go to Column Mappings.

3. You’ll see four tabs: Order, Fulfilment, Product, Inventory.

4. For each tab, you’ll see Neuro’s internal fields (for example order_id, customer_name).

5. Click the pencil icon next to a field and type the header name used in your CSV file.

   • For example, map order_id → PurchaseOrderNumber.

6. Click Save and repeat for any additional fields.

Column names are case‑sensitive. They must exactly match the headers in your CSV files.

Any fields you leave unmapped will use the default system name.

2.6 XML field mapping

If your channel uses XML, you’ll configure mappings with the XML Field Mapping builder:

1. Open XML Field Mappings (this replaces Column Mappings for XML channels).

2. Choose the data type tab: Order, Fulfilment, Product or Inventory.

3. Follow the wizard:

Step 1 – Upload a sample XML file

• Upload a representative XML file.

• Neuro scans the structure and shows:

  • The root element

  • Likely record elements

  • A tree view with sample values

Step 2 – Choose the record element

• Select which element represents a single record (for example ).

• Neuro suggests repeating paths, such as Orders/Order.

• You’ll see how many records were detected.

Step 3 – Map your fields

• For each Neuro field, select the XML element or attribute.

• Use @attributeName for attributes.

• You can map fields inside the record element and global fields outside it.

• Save when done.

Repeat this for any other data types using XML.

XML requirements

• A single root element (for example ).

• Repeating record elements for each record.

• Paths and element names that match your configured mappings.

• Well‑formed XML (valid characters, closed tags, etc.).

• Namespaces are supported; include prefixes in your mappings.

2.7 Auto cleanup

Auto cleanup helps you manage storage and keep your SFTP folders under control:

1. In channel settings, find Enable Auto Cleanup.

2. Turn it on.

3. A table appears listing folders and their cleanup rules:

   • By default, you’ll see entries such as:

     • orders/processed – delete after 7 days

     • products/processed – delete after 7 days

4. You can:

   • Add additional folders, including custom mapped paths

   • Set the number of days after which files should be removed

   • Remove custom entries (defaults cannot be removed)

5. Save your changes.

Only files in listed folders are deleted, so it’s important that these paths match your actual SFTP layout and any folder mappings you’ve configured.

3. File Guidelines

3.1 CSV files

• Maximum lines: 5,000 per file

• Structure:

  • Header row first

  • One row per item when orders or fulfilments contain multiple items

• Filenames: Any name is fine as long as the file is in the correct folder.

• Processing order: Oldest modified file first.

• Extension: Must be .csv.

Orders with multiple items

• Repeat all order‑level columns on each row.

• Use only the item_* columns for item‑specific data.

• Example: A 2‑item order becomes 2 rows that only differ in the item_* fields.

• Neuro groups rows by order_id during import.

Fulfilments with multiple items

• Repeat all non‑item_* columns on each row.

• Use item_* columns for each fulfilled item.

3.2 XML files

• Extension: .xml only.

• Structure: Well‑formed XML with a single root element.

• Records: One repeating element per record (for example one per order).

• Size: For best performance, keep files under ~10 MB (larger files are supported but will take longer).

• Namespaces: Supported; include the prefix in your mappings.

• Attributes: Supported via @attributeName notation.

How XML is processed

• Neuro uses your configured record path to identify each record.

• Each record is processed according to your field mappings.

• Global fields outside the record element are extracted once per file.

• Exports follow the structure you defined in the mapping.

4. Required Fields

4.1 Orders (CSV)

Your Orders CSV must include at least:

order_id order_date 
customer_name 
customer_email 
shipping_address_name 
shipping_address_company_name 
shipping_address_line_one 
shipping_address_line_two 
shipping_address_city 
shipping_address_country_iso_code 
shipping_address_zip 
shipping_address_phone 
billing_address_name 
billing_address_company_name 
billing_address_line_one 
billing_address_line_two 
billing_address_city 
billing_address_country_iso_code 
billing_address_zip 
billing_address_phone 
item_price_currency 
item_discount_currency 
item_discount_tax_currency 

4.2 Products (CSV)

Required columns:

product_id 
product_alt_id 
sku 

4.3 Inventory (CSV)

Required columns:

product_id 
product_alt_id 
sku 
quantity 

4.4 Fulfilments (CSV)

Required columns:

order_id 
tracking_number 
courier 
item_id 
item_product_sku 
item_quantity 

4.5 XML format

For XML channels, required fields are driven by your mappings:

• Root element: Must match the root element you configured.

• Record element: Must match your chosen record path (for example Orders/Order).

• Field paths: Elements and attributes must match the paths configured in the XML mapping wizard.

• XML must be valid and well‑formed.

Neuro validates XML against these rules and reports issues in the channel logs.

5. Sync Intervals

Neuro checks your SFTP folders at the following default intervals (configurable per channel):

You can adjust these intervals to match your volume and operational needs.

6. Best Practices

6.1 File naming

• Use clear, descriptive names, for example:

  • orders_20250508.csv

  • orders_20250508.xml

• Include a timestamp.

• Avoid special characters.

• Make sure the extension matches your channel format (.csv or .xml).

6.2 Processing and monitoring

• Allow each file to finish uploading before the next poll cycle.

• Check the processed/ folder to confirm successful runs.

• Review channel logs for any warnings or errors.

• For XML channels, ensure your sample file and production files share the same structure.

6.3 Security and compliance

• Use strong, unique SFTP passwords.

• Rotate credentials regularly.

• Restrict SFTP access to only the required folders.

• Review auto cleanup settings so you keep the retention period that fits your audit or compliance needs.

6.4 Performance

• Keep files to a reasonable size (a few hundred MB at most; ~10 MB for XML is ideal).

• Avoid dropping dozens of large files at once.

• Use folder mappings to separate imports and exports logically.

• Tune sync intervals based on how frequently you generate files.

6.5 Folder and XML mapping hygiene

• Test new folder mappings with a small file before scaling up.

• Ensure all mapped folders have read/write (and delete, if cleanup is enabled).

• For XML mappings, always:

  • Upload a representative sample file

  • Confirm the record path is correct

  • Test with a small file before large batches

  • Keep your structure consistent across files of the same type

7. Examples

7.1 Orders CSV

order_id,order_date,customer_name,customer_email,shipping_address_name,shipping_address_company_name,shipping_address_line_one,shipping_address_line_two,shipping_address_city,shipping_address_country_iso_code,shipping_address_zip,shipping_address_phone,item_id,item_product_sku,item_quantity 
ORD123,2024-03-20 10:00:00,John Doe,john@example.com,John Doe,ACME Inc,123 Main St,Apt 4B,New York,US,10001,+1234567890,ITEMA,SKU123,1 
ORD123,2024-03-20 10:00:00,John Doe,john@example.com,John Doe,ACME Inc,123 Main St,Apt 4B,New York,US,10001,+1234567890,ITEMB,SKU456,2 

7.2 Fulfilments CSV

order_id,tracking_number,courier,item_id,item_product_sku,item_quantity ORD123,TRK123456,USPS,ITEMA,SKU123,1 
ORD123,TRK123456,USPS,ITEMB,SKU456,2 

7.3 XML example

ORD123 2024-03-20T10:00:00  
John Doe john@example.com    
ITEMA SKU123 1   
ITEMB SKU456 2     

8. Troubleshooting

Connection issues

• Check host, port, username and password.

• Confirm the base path exists.

• Ensure your firewall allows connections from Neuro’s IPs.

• Test your credentials using an SFTP client.

File processing issues

For CSV

• Confirm the file is valid CSV with a header row.

• Stay within the 5,000‑line limit per file.

• Make sure header names match your column mappings exactly (including case).

• Confirm the file extension is .csv.

For XML

• Check the file is well‑formed and valid XML.

• Ensure the root element and record path match your configured mappings.

• Verify field paths and namespaces.

• Confirm the file extension is .xml.

General

• Check file and folder permissions on your SFTP server.

• Make sure files are in the correct folders, especially if you use custom folder mappings.

• Review channel logs for precise error messages.

Sync problems

• Confirm the channel is set to Active.

• Review any rate‑limit or error messages in the logs.

• Check that your sync intervals make sense for your volume.

• Verify that the SFTP server is online and responsive.

Mapping problems

CSV mappings

• Custom column names must exactly match the file headers.

• Ensure all required fields are mapped.

• Watch out for trailing spaces or invisible characters.

XML mappings

• Re‑upload a sample file to recheck structure detection.

• Confirm the record path selects the correct repeating element.

• Verify that all mapped paths exist in the XML.

• Test with a small file before processing larger batches.

Auto cleanup problems

• Confirm folder paths in cleanup settings match your actual SFTP structure.

• Check that the retention period is set as expected.

• Ensure the SFTP user has permission to delete files in cleanup folders.

• Review channel logs for any cleanup‑related errors.

9. Support

If you still have questions or run into issues:

1. Review the channel logs in your Neuro dashboard.

2. Double‑check your CSV headers or XML structure, folder layout and line counts.

3. Confirm that your mappings (column or XML) match your file structure.

4. Test changes with a small sample file.

5. Contact the Neuro Support Team with:

   • The exact error message from the logs

   • A screenshot of your folder structure

   • A sample file, if possible

   • Your SFTP channel configuration details

Neuro’s SFTP channel is designed to meet you where you already work: simple file drops, predictable sync, and clear logging so your operations stay controlled, traceable and easy to manage.