Package Tracking

TimberCloud Storefront — Product Catalog

TimberCloud provides real-time package tracking with automatic status updates, customer notifications, and seamless order status management through integration with the Parcels API.

Overview

The tracking system provides:

Real-time status updates via webhooks and polling
Multi-carrier support for all major carriers
Automatic order updates when packages are delivered
Customer notifications at each tracking milestone
Complete event history for every shipment

How It Works

Dual Update System

TimberCloud uses two methods to ensure tracking is always up-to-date:

Method	Timing	Purpose
Webhooks	Real-time	Instant updates when carrier scans package
Polling	Every 15 minutes	Backup to catch any missed webhooks

This dual approach ensures 99.9% reliability - if a webhook fails, polling catches the update within 15 minutes.

Tracking Flow

1. Order Shipped
   ↓
2. Tracking Number Added
   ↓
3. Registered with Parcels API
   ↓
4. Real-time Updates (Webhook + Polling)
   ↓
5. Customer Notifications
   ↓
6. Package Delivered
   ↓
7. Order Status Updated Automatically

Tracking Statuses

Status	Icon	Description
`pending`	📝	Tracking created, awaiting first scan
`info_received`	📋	Carrier has shipment info
`in_transit`	🚚	Package moving through network
`out_for_delivery`	📦	On vehicle for delivery
`delivery_attempt_failed`	⚠️	Delivery attempted but failed
`delivered`	✅	Package delivered successfully
`exception`	❌	Problem with delivery
`expired`	⏰	Tracking no longer active
`cancelled`	🚫	Shipment cancelled

Supported Carriers

Major Carriers (Automatic Detection)

UPS - All services (Ground, Air, etc.)
FedEx - Express, Ground, Home Delivery
USPS - Priority, Express, First Class
DHL - Express Worldwide

Regional & Freight Carriers

LaserShip
OnTrac
Spee-Dee Delivery
ABF Freight
Estes Express
XPO Logistics
And many more...

The system automatically detects the carrier from the tracking number format.

Adding Tracking Numbers

From Order Details

Open the order in your admin panel
Navigate to the Shipping section
Click "Add Tracking Number"
Enter the tracking number
Select carrier (optional - auto-detected)
Add notes if needed
Save

Automatic from Label Generation

When you generate a shipping label through TimberCloud:

Tracking number is automatically captured
Linked to the order
Registered for tracking updates
Customer is notified automatically

Multiple Tracking Numbers

Orders can have multiple tracking numbers:

Split shipments from different locations
Separate packages for large orders
Different carriers for different items

Real-Time Updates

Webhook Integration

When Parcels API receives carrier updates:

Webhook sent to TimberCloud
Tracking record updated instantly
Socket event emitted to connected clients
Frontend updates in real-time
Customer notification triggered (if enabled)

Polling Backup

Every 15 minutes, the system:

Queries all active (non-delivered) tracking numbers
Fetches latest status from Parcels API
Updates any changed records
Checks if all packages for an order are delivered
Updates order status if complete

Automatic Order Status Updates

When all tracking numbers for an order show as "Delivered":

System automatically updates order status to "Delivered"
Sets dateDelivered to actual delivery timestamp
Marks order as shipped = true
Emits real-time update to admin dashboard
Triggers delivery confirmation notification

Customer Experience

Order Tracking Page

Customers can view tracking on their order page:

Current status with icon
Estimated delivery date
Complete event timeline
Carrier name and service
Direct link to carrier tracking

Event Timeline

Each tracking update shows:

Date and time of event
Location (city, state, country)
Status description
Event details

Email Notifications

Configure notifications for:

Event	Description
Shipped	Tracking number added
In Transit	First movement scan
Out for Delivery	On vehicle for delivery
Delivered	Package delivered
Exception	Problem with delivery

Admin Dashboard

Tracking Overview

View all active shipments:

Filter by status
Search by tracking number
Sort by date or carrier
Quick status indicators

Manual Sync

Force an update for any tracking number:

Open tracking record
Click "Sync Now"
Fetches latest from Parcels API
Updates immediately

Bulk Actions

Sync all tracking for an order
Export tracking data
Update carrier information
Add notes

Tracking Data

Information Tracked

Field	Description
`tracking_number`	The carrier tracking number
`carrier`	Carrier name (UPS, FedEx, etc.)
`carrier_code`	Carrier identifier
`current_status`	Latest status
`status_details`	Current status description
`estimated_delivery`	Expected delivery date/time
`actual_delivery`	When package was delivered
`shipped_date`	When package was shipped
`origin`	Ship-from location
`destination`	Ship-to location
`status_history`	Complete event timeline
`last_checked`	When last synced

API Endpoints

Create Tracking Number

POST /api/tracking-numbers
{
  "tracking_number": "1Z999AA10123456784",
  "order": 123,
  "carrier": "UPS",
  "notes": "Package 1 of 2"
}

Sync Tracking Number

POST /api/tracking-numbers/:id/sync

Sync All Tracking for Order

POST /api/tracking-numbers/sync-order/:orderId

Webhook Endpoint (Parcels API)

POST /api/tracking-numbers/webhook
// Called automatically by Parcels API

Configuration

Environment Variables

# Required
PARCELSAPP_API_KEY=your_api_key_here
 
# Optional (for webhook setup)
PARCELSAPP_WEBHOOK_URL=https://your-domain.com/api/tracking-numbers/webhook

Polling Settings

Default: Every 15 minutes

To adjust frequency, modify the cron schedule:

// Every 15 minutes (default)
'*/15 * * * *'
 
// Every 30 minutes
'*/30 * * * *'
 
// Every hour
'0 * * * *'

Best Practices

Add tracking promptly - Enter tracking numbers as soon as labels are generated
Use automatic capture - Let label generation auto-populate tracking
Monitor exceptions - Set up alerts for delivery problems
Keep customers informed - Enable email notifications
Verify tracking numbers - Ensure correct format before saving

Troubleshooting

Tracking Not Updating

Check:

Parcels API key is configured
Tracking number format is valid
Carrier is supported
Webhook URL is accessible (for real-time)

Solution:

Try manual sync from admin
Verify API credentials
Check server logs for errors

Order Not Marked Delivered

Check:

All tracking numbers for the order
Each tracking shows "delivered" status
No tracking numbers stuck in transit

Solution:

Manually sync all tracking
Check individual tracking statuses
Verify all packages are accounted for

Webhook Not Receiving Updates

Check:

Webhook URL is publicly accessible
SSL certificate is valid
No firewall blocking requests
Server is running

Solution:

Test webhook URL accessibility
Check ngrok setup (for development)
Review server logs
Verify Parcels API configuration

Tracking Number Not Found

Check:

Number is entered correctly
Carrier has received the package
Allow 24 hours after label creation

Solution:

Wait for carrier's first scan
Verify number with carrier directly
Check for typos in tracking number

Shipping Dashboard Inventory Overview