External Couriers
Third-party delivery providers integrated into Deliverty Hub through the courier plugin system.
What Are External Couriers?
An external courier is a third-party logistics provider that your organization connects to through Deliverty Hub. Instead of dispatching tasks to your own agents, external couriers route deliveries to an outside provider's fleet via their API.
External couriers are implemented through a plugin system on the backend. Each external courier provider has a corresponding plugin that handles API communication, order creation, status synchronization, and tracking data. This architecture allows new providers to be added without modifying the core platform.
External courier integrations are built as modular plugins. Each plugin implements a standard interface for creating shipments, cancelling orders, and polling for status updates. Refer to the Courier Guide for technical details on the plugin system.
Courier Statuses
Every courier (internal or external) has an operational status that determines whether it can be used for task dispatch:
| Status | Description | Can Accept Tasks? |
|---|---|---|
| ACTIVE | The courier is fully operational and ready to accept delivery tasks. | Yes |
| PENDING | The courier has been created but is not yet configured or activated. Awaiting setup completion. | No |
| BLOCKED | The courier has been disabled by an administrator, possibly due to service issues or contract expiry. | No |
| IN_REVIEW | The courier is under review — typically a new external provider whose credentials and integration are being validated. | No |
Tasks can only be dispatched to couriers in ACTIVE status. If you attempt to assign a task to a courier that is PENDING, BLOCKED, or IN_REVIEW, the operation will fail. Ensure your external courier is fully activated before routing tasks to it.
Activating an External Courier
Setting up an external courier involves several steps to ensure the integration is properly configured:
Add the Courier
Navigate to Fleet > Couriers and click Add Courier. Select the External type and choose the provider from the list of available plugins. The courier is created in PENDING status.
Enter Credentials
Provide the API credentials required by the third-party provider. These are stored per-organization, so each tenant has their own account with the external service. Common credential fields include API key, secret, and account/merchant ID.
Configure Availability
Set the availability schedule — which days of the week the courier operates. This prevents tasks from being routed to the provider on days when their service is unavailable.
Validate & Activate
The system verifies the credentials by making a test API call to the provider. Once validation succeeds, you can set the courier to ACTIVE status.
Per-Organization Credentials
External courier credentials are scoped to each organization. This means:
- Organization A can connect to Provider X with their own API key, while Organization B connects to the same Provider X with a different API key.
- Billing, rate limits, and service agreements are separate per organization.
- Credentials are stored securely and are never shared between tenants.
- If a credential is revoked or expires, only the affected organization's courier integration is impacted.
Availability Schedules
External couriers support day-of-week availability schedules. This allows you to define which days the courier is available to accept deliveries:
| Day | Available | Notes |
|---|---|---|
| Sunday | Configurable | Some providers may not operate on weekends |
| Monday | Configurable | — |
| Tuesday | Configurable | — |
| Wednesday | Configurable | — |
| Thursday | Configurable | — |
| Friday | Configurable | Some providers may have reduced hours |
| Saturday | Configurable | Some providers may not operate on weekends |
When a task is dispatched on a day the external courier is marked as unavailable, the system will not route the task to that courier. This helps prevent failed dispatches and ensures tasks are only sent to providers that are operational.
Task Dispatch to External Couriers
When a task is routed to an external courier, the following process occurs:
- Order creation: The platform calls the external provider's API (via the courier plugin) to create a shipment/order with the task's pickup and delivery details.
- External tracking ID: The provider returns a tracking number or reference ID, which is stored on the task for reference.
- Status synchronization: The platform periodically polls the provider's API (or receives webhooks) to sync delivery status updates back into Deliverty Hub.
- Completion: When the external provider marks the delivery as complete, the corresponding task in Deliverty Hub is updated to
COMPLETED.
GPS tracking granularity for external couriers depends on what the third-party provider exposes through their API. Some providers offer real-time GPS coordinates, while others only provide status checkpoints (picked up, in transit, delivered). The live tracking map will show whatever data is available.
Managing External Couriers
From the dashboard, you can perform the following actions on external couriers:
- View status: See the courier's current status and last connectivity check.
- Update credentials: Rotate API keys or update account details without recreating the courier.
- Modify schedule: Change the day-of-week availability as your operational needs evolve.
- Block/unblock: Temporarily disable a courier by setting its status to
BLOCKED, then re-activate it when the issue is resolved. - View task history: See all tasks that have been dispatched through this courier, including their current status and any external tracking references.