Device Shipments

Overview

ARROW integrates with EasyPost to provide comprehensive shipping management for device deployments. This includes outbound shipments to clients, return label generation, and real-time tracking synchronization.

EasyPost Integration

ARROW uses EasyPost as its shipping provider to create labels, calculate rates, and track shipments across multiple carriers.

Supported Carriers

The system supports multiple carriers with organization-level preferences:

Carrier	Use Case	Notes
FedEx	Primary domestic carrier	Requires phone number on addresses
UPS	Alternative domestic option	Standard address requirements
USPS	Cost-effective option	Limited tracking granularity
DHL	International shipments	Customs documentation required

Organizations can set default carrier preferences, which can be overridden per-shipment when needed.

Domestic vs. International Shipping

Shipment Type	Requirements	Additional Steps
Domestic	Standard address validation	None
International	Customs information	Harmonized codes, declared values, contents description

Shipment Creation Workflow

When a device is ready for shipment, the following process occurs:

sequenceDiagram
    participant Admin
    participant Portal
    participant Backend
    participant EasyPost
    participant Carrier
    participant User

    Admin->>Portal: Create Shipment
    Portal->>Backend: Request Labels
    Backend->>EasyPost: Create Outbound Shipment
    EasyPost->>EasyPost: Generate Rates
    Backend->>EasyPost: Buy Outbound Label
    Backend->>EasyPost: Create Return Shipment
    Backend->>EasyPost: Buy Return Label
    EasyPost-->>Backend: Labels & Tracking Numbers
    Backend->>EasyPost: Create Trackers
    Backend-->>Portal: Shipment Created

    Backend->>Carrier: Ship Device
    Carrier->>EasyPost: Tracking Updates
    EasyPost->>Backend: Webhook: Status Change
    Backend->>Backend: Update Shipment Status
    Backend->>Backend: Update Device Request Status
    Backend-->>Portal: Status Updated
    Portal-->>User: Device In Transit

    Carrier->>User: Deliver Device
    Carrier->>EasyPost: Delivered Event
    EasyPost->>Backend: Webhook: Delivered
    Backend->>Backend: Set Status to On-Site
    Backend-->>Portal: Device Delivered

Label Generation

For each shipment, the system generates:

1. Outbound Label: Ships device to the client
2. Return Label: Pre-paid label included with shipment for device return

Labels are generated in ZPL format and converted to PDF for printing.

Address Validation

Before creating shipments, addresses are validated:

• Required Fields: Street address, city, state/province, postal code, country
• Phone Number: Required for FedEx shipments
• Company Name: Recommended for business addresses

Note Address validation failures will prevent shipment creation. Ensure addresses are complete and accurate before requesting labels.

Parcel Information

Standard parcel dimensions are pre-configured based on device specifications. Custom dimensions can be specified for non-standard shipments.

Shipment Tracking

ARROW provides real-time tracking synchronization through EasyPost webhooks and scheduled status checks.

Tracking Status Values

stateDiagram-v2
    [*] --> PreTransit: Label Created
    PreTransit --> InTransit: Carrier Pickup
    InTransit --> OutForDelivery: Local Facility
    OutForDelivery --> Delivered: Delivered to User
    Delivered --> [*]: On-Site

    InTransit --> ReturnToSender: Return Initiated
    ReturnToSender --> [*]: Returned

    PreTransit --> Cancelled: Voided
    InTransit --> Failure: Delivery Issue
    Failure --> [*]: Admin Review

Status	Description
pre_transit	Label created, awaiting carrier pickup
in_transit	Package in carrier network
out_for_delivery	Out for final delivery
delivered	Successfully delivered
return_to_sender	Package being returned
failure	Delivery attempt failed
cancelled	Shipment cancelled/voided

Status Synchronization

The system synchronizes tracking status through two mechanisms:

1. Webhooks: Real-time updates from EasyPost when status changes
2. Scheduled Sync: Hourly background job to catch any missed updates

Device Request Status Updates

Shipment status changes automatically update the associated device request:

Shipment Status	Device Request Status	Description
pre_transit	shipping	Label created, awaiting carrier pickup
in_transit	in-transit	Package in carrier network
out_for_delivery	in-transit	Out for delivery to destination
delivered	on-site	Package delivered to user
Return delivered	returned	Device returned to warehouse
failure / cancelled	pending	Issue requiring admin review

Important The system will never change a device request status from “complete” based on shipment updates. This protects finalized engagements from accidental status changes.

Accessing Tracking Information

Users can access tracking information through:

• Portal: View tracking status and history in the device request details
• Tracking URL: Direct link to carrier tracking page
• Email Notifications: Automated updates on status changes (if configured)

Return Shipments

Return labels are generated with the outbound shipment and included in the device package.

Return Label Usage Detection

The system monitors return labels to detect when they’ve been used:

• Scanned by Carrier: Label enters carrier network
• Tracking Updates: Status changes from pre_transit to in_transit
• Delivery Confirmation: Package arrives at warehouse

Manual Tracking Entry

For devices returned via alternative carriers (not using the provided return label):

1. Navigate to the device request details
2. Enter the alternative carrier tracking number
3. System will attempt to track via EasyPost’s universal tracking

Return Label Refunds

If the return label is not used (device returned via alternative method or picked up):

• System detects unused label status
• Automatic refund request submitted to EasyPost
• Credit applied to organization’s shipping account

Shipment Completion

When a return shipment is delivered, the following timestamps are captured:

Timestamp	Purpose	Source
Pickup Time	Billing calculation start	Outbound delivery confirmation
Delivery Time	Warehouse arrival	Return delivery confirmation

These timestamps support accurate billing for engagement duration.

Troubleshooting

Address Validation Failures

Symptom: Shipment creation fails with address validation error

Solutions:

• Verify all required fields are populated
• For FedEx shipments, ensure phone number is included
• Check for typos in postal codes
• Verify country code format (ISO 2-letter codes)

Tracking Status Not Updating

Symptom: Shipment shows stale tracking information

Solutions:

• Wait for the hourly sync cycle to complete
• Check EasyPost dashboard for webhook delivery status
• Verify the tracking number is valid with the carrier
• Contact support if status is stuck for more than 24 hours

Return Label Not Refunding

Symptom: Unused return label not credited

Solutions:

• Verify the label was truly unused (no carrier scans)
• Check that the device request has been marked complete
• Refund requests may take 24-48 hours to process
• Contact support for labels older than 30 days

Manual Tracking Number Issues

Symptom: Alternative tracking number not tracking properly

Solutions:

• Verify the tracking number format is correct
• Ensure the carrier is supported by EasyPost
• Some regional carriers may have limited tracking support
• Enter the number exactly as provided by the carrier

Related Documentation

• Device Management - Complete device lifecycle management
• Auto-Inventory - Automated hardware inventory collection
• Device Requests - Creating and managing device requests