Skip to main content

Trading partner file exchange

Exchange orders and shipments with retailers, 3PLs, and suppliers over SFTP. Orderly connects out to the partner server on a schedule, turns their files into Orderly orders and shipment updates, and delivers your released orders and shipment confirmations back. Every file is kept immutably with a full processing history: nothing is ever silently dropped or overwritten.

Available on the Scale plan. Supported file formats: CSV, JSON, XML, fixed width, and EDI X12 (Enterprise).

Setting up a partner​

  1. Exchange > Partners > New partner. Pick the kind and which documents you exchange (receive orders, receive shipment updates, send released orders, send shipment confirmations).
  2. Add the SFTP connection. Hostname, port, username, password or SSH private key, the folders for each direction, archive and error folders, the file naming pattern, and how often to check. Credentials are stored encrypted and never shown again.
  3. Test the connection. The first successful test captures the server's host key fingerprint. Verify it with your partner, then confirm it. Transfers stay disabled until the fingerprint is confirmed; this protects you from server impersonation.
  4. Create and publish a mapping. A mapping tells Orderly how the partner's columns translate to order and shipment fields. Test it with a sample file first: the dry run shows exactly which records would be created and any validation errors, without touching real data.
  5. Files start flowing on the connection's schedule. Use Check now any time.

Give your partner the Orderly egress IP for their firewall allowlist (shown on the connection page; ask support if you need it in writing).

How files are processed​

Every discovered file is downloaded, stored immutably, and checksummed: the same file twice never creates duplicate orders or shipments. It is then validated, mapped through your published mapping version, and applied: order files create Orderly orders (which flow through your dispatchers and order release like any other channel), shipment files update the matching orders. Successful files move to your archive folder on the partner server; failed files move to the error folder and appear in Exchange > Exceptions with the exact validation errors.

Outbound files are generated when you release an order or purchase a label, uploaded under a temporary name, and renamed atomically so your partner never reads a half-written file. Failed deliveries retry with increasing delays and park in Exceptions if they exhaust.

Mappings, step by step​

A mapping teaches Orderly how a partner's file becomes an order or a shipment (or how yours are written on the way out). You never write code: the builder generates everything from three choices per field.

  1. Exchange > Mappings > New mapping. Name it, pick the partner (or make it a template for all partners), the direction, whether the file holds orders or shipments, and the format: CSV, JSON, XML, or fixed width. For XML the builder reads paths from your sample; for fixed width each field takes a start column and a width instead of a header.
  2. Paste a sample file. The builder reads the columns and offers Match columns automatically, which pairs obvious headers (PO Number, SKU, Qty, Ship To Zip) with the right Orderly fields. Adjust anything it missed.
  3. Pick the key column. Rows sharing this value become one order, and its rows become the line items. The same key received twice never creates a duplicate.
  4. Test with the sample. The dry run shows exactly which records would be created and every validation problem, without touching real data.
  5. Publish. Files start processing against this version. Published versions are frozen; edits create a new draft you test and publish the same way, and every document remembers which version processed it.

Fields you can map to​

Orders: order number, line item SKU, quantity, unit price and name, customer email and name, the full ship-to address (name, company, street, city, state, ZIP, country, phone), requested ship date, currency, and an order note.

Shipments: shipment reference, tracking number, carrier, service, status, ship date, and order number.

Transforms​

Each field can clean its value on the way in: trim spaces, UPPERCASE or lowercase, Number (for quantities), Money to cents, and Date (accepts common formats, stores ISO). A field marked required sends the whole record to Exceptions when missing, instead of creating a bad order.

Worked example​

Partner file:

PO Number,SKU,Qty,Unit Price,Ship To Name,Ship To Zip
PO-1001,WIDGET-A,2,19.99,Jane Doe,08520
PO-1001,WIDGET-B,1,5.00,Jane Doe,08520

Key column PO Number; map SKU, Qty (Number), Unit Price (Number), Ship To Name, and Ship To Zip (required). The two rows become one order, PO-1001, with two line items. That is the whole mapping.

EDI documents (850, 855, 856, 810, 997) need no mapping at all: the standard structure is understood natively.

The document lifecycle​

Received, Validating, Processing, Action required, Ready to send, Sent, Acknowledged, Rejected, Completed. Documents in Action required or Rejected wait in the Exceptions queue where you can inspect the raw file and errors, retry after fixing the mapping, ignore with a note, or escalate.

Transports​

  • SFTP and FTPS: Orderly connects out to the partner's server on a schedule from a fixed IP. SFTP pins the host key; FTPS verifies the TLS certificate.
  • AS2 over HTTPS (beta): partners POST signed X12 documents to a private intake URL and receive a synchronous acknowledgment (MDN). Outbound documents are signed with your certificate and delivered to the partner's AS2 URL; a processed MDN completes them. Encrypted AS2 payloads are not supported yet and are refused with a clear error. Requires the Enterprise plan.
  • Email attachments: point any inbound-email service at the connection's intake URL; attachments run through the standard pipeline.
  • Direct API: systems can submit documents straight to POST /api/v1/exchange/documents.

The intake URL shown when you create an AS2, email, or API connection is the shared secret for that connection. Treat it like a password; create a new connection to rotate it.

EDI (X12)​

On the Enterprise plan, partners can exchange native X12 documents over the same SFTP connections:

  • Inbound 850 purchase orders become Orderly orders automatically. No mapping is needed; the standard 004010 structure is understood, and invalid lines surface as validation errors instead of bad orders.
  • 855 acknowledgments are generated and delivered automatically when a received 850 is accepted.
  • 856 advance ship notices and 810 invoices are generated when you purchase a label for the partner's order.
  • 997 functional acknowledgments flow both ways: Orderly acknowledges every received interchange, and partner 997s move your sent documents to Acknowledged or Rejected. Sent EDI documents wait in the Sent state until the acknowledgment arrives.

Set the interchange identifiers (ISA sender and receiver, with qualifiers) and pick the transaction sets under the partner's EDI settings. Control numbers are allocated automatically per partner. Documents from a partner in test mode carry the T usage flag.

API​

Everything is available programmatically under /api/v1/exchange: partners, connections (test, confirm-host-key, poll-now, pause, resume), documents (list, detail with timeline, raw file, retry, ignore, escalate, direct submission), mappings (draft, publish, test), and stats. Scopes: exchange:read, exchange:write.