SFTP Orders Upload

This document is for new or current Northbeam customers who wish to send Orders to Northbeam without using our Orders API or native Shopify connector. Common use cases include historical order backfills and recurring order uploads from systems without API integration resources.

Under the hood, this service takes your CSV file, validates it, splits it into batches, and uploads it through our standard Orders API.

---

Table of Contents

• Step 1. Request Access
• Step 2. Format Your CSV
  • Formatting Rules
  • Field Reference
• Step 3. Upload Your File
• Step 4. Confirm Success or Troubleshoot Errors
  • Common Errors and Fixes

---

Step 1. Request Access

Submit a support ticket to request SFTP access. Northbeam will assign you a User and Password.

Host: sftp.robot.northbeam.io
User: XXX_orders
Password: XXX
Port: 22

Using your preferred SFTP client, connect to your Northbeam SFTP instance with the details provided.

---

Step 2. Format Your CSV

Each file must follow this template exactly or the upload will fail:

📄 SFTP Orders Upload Template

Formatting Rules

These rules are strict — most failed uploads are caused by one of the following:

1. Required columns must be present in your file. Optional columns may be omitted entirely if you have no data for them.
2. Field names are case-sensitive and must match the template exactly.
3. Product fields are pluralized: products_id, products_name, products_quantity, products_price. Singular field names (product_id, product_name, etc.) will fail validation.
4. tax and shipping_cost cannot be empty. Pass 0 if there is no value to report.
5. time_of_purchase must use the ISO-8601 standard (e.g. 2026-03-08T09:23:45.000Z).
6. Orders with multiple products use one row per product, repeating the same order-level values (order_id, totals, etc.) on each row. Our system consolidates rows with the same order_id into a single order.

Field Reference

---

Step 3. Upload Your File

Place your .CSV file in your SFTP directory. Processing begins automatically — no additional ingestion step is required on your end.

Limits:

• Each file must not exceed 200 MB (approximately 1 million records, depending on your data).
• For larger datasets, split your data into multiple files.

---

Step 4. Confirm Success or Troubleshoot Errors

Once you upload a file, our automation will process it within a few moments and move it to one of two folders:

⚠️

Validation is all-or-nothing.

If any row in your file fails validation, the entire file is rejected and moved to /invalid_files. Fix all errors in the error report before re-uploading.

• /processed_files — the file was processed successfully and orders will be available after the next data processing cycle.
• /invalid_files — the file contained validation errors. An error report (<your filename>_errors.txt) will be created alongside it with row-level details for debugging.

If your file lands in /invalid_files, review the error report, fix the issues, and re-upload the corrected file.

Example error report:

Validation Error Report
File: orders_uploads/925160f8-ecc3-4457-8c3e-b75fe5dbf0ac/broken_file_sample.csv
Client ID: 925160f8-ecc3-4457-8c3e-b75fe5dbf0ac
Timestamp: 2026-01-30T18:10:18.917640Z
Total Invalid Orders: 3
================================================================================
Row 1:
  Order ID: O12345
  Customer ID:
  Validation Errors:
    - Field: customer_id
      Type: string_too_short
      Message: String should have at least 1 character
Row 3:
  Order ID: O726883481
  Customer ID: 815186642
  Validation Errors:
    - Field: time_of_purchase
      Type: value_error
      Message: Value error, Invalid ISO TS
Row 4:
  Order ID: O7292339997
  Customer ID: 812197138
  Validation Errors:
    - Field: currency
      Type: string_too_short
      Message: String should have at least 3 characters

Common Errors and Fixes

After fixing errors, simply re-upload the corrected file to the same directory.