SFTP Relay

SFTP relay delivers shipment status updates as JSON files to Duty Pro’s hosted SFTP server. You connect to the server and download files at your convenience. This is one of two status relay methods supported by Duty Pro (the other being webhooks).

How it works

Duty Pro operates a pull-model SFTP server — rather than pushing files to your server, Duty Pro writes status files to its own SFTP server and you connect to download them.

1. Status events are generated as shipments progress (created, payment received, expired, etc.).
2. Duty Pro batches events and writes JSON files to your directory on the SFTP server.
3. You connect via SFTP and download the files on your own schedule.

Setup

Configure SFTP relay in the dashboard under Settings > Status Relay:

1. Select SFTP as the relay method.
2. The dashboard displays your SFTP connection details:

Field	Description
Host	SFTP server hostname
Port	SFTP port (typically 22)
Username	Your account-specific username
Password	Your SFTP password (shown once on setup; can be reset)

You can reset your SFTP password at any time from the dashboard.

File structure

Files are organized by date in your directory:

/{account_id}/{mode}/{YYYY-MM-DD}/dutypro_updates_YYYYMMDDTHHMMSSZ.json

Path segment	Description
{account_id}	Your unique account ID
{mode}	production for live shipments, test for test shipments
{YYYY-MM-DD}	Date the file was generated
dutypro_updates_...	Timestamped filename

File format

Each file contains a JSON array of status update objects. Multiple events are batched into a single file per processing cycle.

[
  {
    "reference": "ORD-2026-00123",
    "held": true,
    "held_on_error": false,
    "canceled": false
  },
  {
    "reference": "ORD-2026-00124",
    "held": false,
    "held_on_error": false,
    "canceled": false
  }
]

Field reference

Field	Type	Description
reference	string	Your shipment reference number
held	boolean	true when the shipment is held and customs payment is required
held_on_error	boolean	true if the shipment is held because of a calculation error
canceled	boolean	true if the payment has expired

Events

Event	held	canceled	Trigger
Payment required	true	false	Shipment created with fees > 0
Payment received	false	false	Consignee completed payment
No payment required	false	false	Shipment created with fees = 0
Payment expired	false	true	Payment deadline passed

Custom field names

If your receiving system expects different field names, contact the Duty Pro team to configure custom key mappings for your account.

Processing schedule

Duty Pro generates SFTP status files every 15 minutes. Pending status events are batched by account and mode (live/test) and written as a single file per batch.

Test mode behavior

In test mode, SFTP files are generated and stored internally but not pushed to the SFTP server. You can download them from the dashboard for inspection. This prevents test data from mixing with production files.

Test files use the test mode path (e.g., /{account_id}/test/{date}/...), keeping them separate from production files at /{account_id}/production/{date}/....

Retry behavior

If file writing fails, Duty Pro retries with the same backoff schedule as webhooks:

Attempt	Delay
1st retry	5 minutes
2nd retry	10 minutes
3rd retry	15 minutes
4th retry	20 minutes

After 4 failed attempts, the relay is marked as FAILED and visible in the dashboard.

Monitoring

Relay delivery status is visible in two places:

• Shipment detail view — The “Status Relay Log” section shows the relay event, file name, file size, and delivery status.
• Settings > Status Relay — Shows overall configuration and recent delivery history.