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
- Exchange > Partners > New partner. Pick the kind and which documents you exchange (receive orders, receive shipment updates, send released orders, send shipment confirmations).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Test with the sample. The dry run shows exactly which records would be created and every validation problem, without touching real data.
- 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: standard AS2 (RFC 4130). Partners POST S/MIME messages to a private intake URL and receive a synchronous acknowledgment (MDN); outbound documents are posted to the partner's AS2 URL. See AS2 below. 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: an API connection's system posts JSON with base64
attachments(each withfilenameandcontent_base64) to the connection's intake URL, the same body an email connection receives. Systems holding an Orderly API key can also submit documents straight toPOST /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.
Rotating an intake URL
Rotate a connection's intake URL when it may have been seen by someone who
should not have it: a former member, a read-only member before intake tokens
were hidden from read-only callers, a forwarded email, or a log. Rotating
issues a new token, so the connection's intake URL changes. The previous URL
stops working at once, and documents sent to it are refused with 404, so
give the partner or inbound email service the new URL straight away.
Rotate with POST /api/v1/exchange/connections/{id}/intake-token/rotate
(scope exchange:write). The response carries the new intake_token and
intake_url. Credentials, certificates and the rest of the connection's
settings are not changed. SFTP and FTPS connections have no intake URL and
answer 409. Rotation is refused during staff impersonation.
AS2
Messages follow RFC 4130 with S/MIME (RFC 8551), so any standard AS2 product can exchange with Orderly.
- Signing: the document travels as a MIME entity (its Content-Type,
Content-Transfer-Encoding: binaryand a file name) inside amultipart/signedmessage. The detached CMS signature covers that whole entity, headers and body, and themicalgparameter names the digest (sha-256,sha-384orsha-512). Orderly signs with SHA-256 by default and never with SHA-1 or MD5. - Encryption (optional): the signed message, or the document entity when
signing is off, is wrapped in CMS enveloped data for the partner's
certificate (
application/pkcs7-mime; smime-type=enveloped-data), with AES-256-CBC by default (AES-128 and AES-192 can be chosen). - MDNs: by default Orderly asks for a signed receipt. The receipt's
Received-Content-MICmust equal the digest of what was sent (the signed entity, or as RFC 4130 section 7.3.1 sets out for unsigned messages), and a signed receipt must verify against the partner's certificate. A receipt that fails either check, or reports an error, is a failed delivery and is retried. Setmdn_modetounsignedfor partners that only return unsigned receipts, ornonefor partners that return no receipt (the HTTP status then decides). - Receiving: the message's
AS2-FromandAS2-Tomust match the connection. Orderly decrypts with its own key, verifies the signature against the partner's certificate and answers with an MDN carrying the MIC, signed when the partner asks for a signed receipt. A message that fails any check is answered with aprocessed/errorMDN naming the reason (authentication-failed,decryption-failed,insufficient-message-security), and nothing is processed. - What Orderly accepts from partners: signatures with SHA-256, SHA-384 or SHA-512, by RSA or ECDSA keys; SHA-1 and MD5 signatures are refused. Encrypted messages with AES-128, AES-192 or AES-256 in CBC mode, or Triple-DES for older systems, with the key transported by RSA (PKCS#1 v1.5 or OAEP). Compressed messages and asynchronous MDNs are not supported.
Replies Orderly generates for an AS2 partner (855 acknowledgments and 997s) are sent back over the same AS2 connection, with the usual retries.
AS2 connection settings
| Setting | Meaning |
|---|---|
as2_url | The partner's AS2 URL: HTTPS on a public host. |
as2_from / as2_to | Your AS2 identifier and the partner's (case sensitive). |
sign_outbound, signing_algorithm | Sign outbound messages (default yes, sha256). |
encrypt_outbound, encryption_algorithm | Encrypt outbound messages (default no, aes256-cbc). |
mdn_mode | signed (default), unsigned or none. |
require_signed_inbound | Refuse unsigned messages (default yes). |
require_encrypted_inbound | Refuse unencrypted messages (default no). |
Secrets: certificate and private_key (yours, RSA or EC, with an
optional passphrase) and partner_certificate. They are write-only.
Every setting and certificate can be changed later with
PATCH /api/v1/exchange/connections/{id}, for example when the partner
moves to a new URL or either side renews a certificate. Send only what
changes: {"secrets": {"partner_certificate": "-----BEGIN CERTIFICATE-----..."}}.
Fields that belong to another transport are refused with 400, and a
private key that does not belong to your certificate is refused.
EDI (X12)
On the Enterprise plan, partners can exchange native X12 documents over the same SFTP, FTPS and AS2 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 (edit, test, confirm-host-key, poll-now, pause,
resume, intake-token/rotate),
documents (list, detail with timeline, raw file, retry, ignore,
escalate, direct submission), mappings (draft, publish, test), and
stats. Scopes: exchange:read, exchange:write.