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: it writes status files to its own server, and you connect to download them on your own schedule.

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.

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 from the dashboard)

File structure

Files are organized by date in your directory:

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

Path segment	Description
{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.

[
  {
    "event": "shipment_created",
    "reference": "ORD-2026-00123",
    "shipment_status": "PENDING",
    "test": false,
    "email_sent": 0,
    "sms_sent": 0,
    "held": true,
    "held_on_error": false,
    "canceled": false
  },
  {
    "event": "payment_completed",
    "reference": "ORD-2026-00124",
    "shipment_status": "PAID",
    "test": false,
    "email_sent": 1,
    "sms_sent": 1,
    "held": false,
    "held_on_error": false,
    "canceled": false
  }
]

Field reference

Field	Type	Description
event	string	The event key that triggered this entry (e.g. shipment_created, payment_completed)
reference	string	Your shipment reference number
shipment_status	string	The shipment’s current payment status (PENDING, PAID, FAILED, or EXPIRED)
test	boolean	true for shipments created with a test API key (dp_test_...), false for live shipments. Matches the {mode} path segment
email_sent	number	Number of emails successfully sent to the consignee for this shipment
sms_sent	number	Number of SMS messages successfully sent to the consignee for this shipment
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

The full list of available events is shown in the dashboard under Settings > Status Relay. From that screen you can also choose which events should be relayed; unchecked events are skipped.

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

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

Retry behavior

If file writing fails, Duty Pro retries with the following backoff schedule:

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.
• Monitoring > Status Relay Log: shows recent delivery history for all shipments.