Tracking Parcels

This guide explains how to use the Tracking Parcels functionality within the Shipping Channels API.

What are Tracking Parcels?

Tracking Parcels represent shipments you want to monitor through the Shipping Channels platform. Each tracking parcel is:

• Associated with a specific Shipping Channel
• Identified by a tracking number
• Updated with status changes automatically
• Queryable through the API

Creating Tracking Parcels

You can create tracking parcels by providing:

{
  "tracking_number": "1234567890",
  "shipping_channel_id": "ch_123456",
  "reference": "order-123",
  "description": "Package for John Doe",
  "recipient": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "postal_code": "10001",
      "country": "US"
    }
  }
}

Required fields:

• tracking_number: The carrier's tracking number
• shipping_channel_id: ID of an active shipping channel

Optional fields:

• reference: Your internal reference (like order number)
• description: Description of the contents
• recipient: Recipient information

Tracking Parcel Statuses

Tracking parcels go through various statuses throughout their journey:

Status	Description
created	The tracking parcel has been created.
waiting_for_shipment	The shipment is waiting to be handed over to the carrier.
in_transit	The shipment is on its way to the recipient.
delivered	The shipment has been delivered to the recipient.
returned	The shipment has been returned to the sender.
delivered_with_exception	The shipment was delivered, but there was an issue (e.g., left with a neighbor).
error	An error occurred during tracking.
not_recognized	The tracking number is not yet recognized by the carrier.
ready_for_pickup	The shipment is ready for pickup by the recipient at a designated location.
out_for_delivery	The shipment is out for delivery to the recipient.
cancelled	The shipment has been cancelled.
on_hold	The shipment is on hold, awaiting further action.
delayed	The shipment is delayed.
pending	The tracking status is pending.
customs	The shipment is currently in customs.
damaged	The shipment has been damaged.

Each shipping provider has their own status codes that are mapped to these standard statuses for consistency.

Status Updates

The platform polls shipping providers regularly to update tracking statuses:

1. Updates occur automatically based on provider information
2. Each status update creates a TrackingParcelStatusUpdate record
3. Status changes trigger webhook notifications if configured
4. Full status history is maintained and accessible via API

Retrieving Tracking Information

You can retrieve tracking information in several ways:

1. Get a specific tracking parcel: Detailed view of a single tracking parcel
2. List tracking parcels: Paginated list with filters
3. Get tracking history: Complete status history for a tracking parcel

Tracking History Example

{
  "data": {
    "id": "tp_123456",
    "tracking_number": "1234567890",
    "shipping_channel_id": "ch_123456",
    "status": "delivered",
    "reference": "order-123",
    "created_at": "2025-04-06T10:00:00Z",
    "updated_at": "2025-04-07T12:00:00Z",
    "status_updates": [
      {
        "id": "tpu_123456",
        "status": "delivered",
        "location": "New York, NY",
        "description": "Delivered, Front Door",
        "timestamp": "2025-04-07T12:00:00Z"
      },
      {
        "id": "tpu_123455",
        "status": "out_for_delivery",
        "location": "New York, NY",
        "description": "Out for delivery",
        "timestamp": "2025-04-07T08:30:00Z"
      },
      {
        "id": "tpu_123454",
        "status": "in_transit",
        "location": "New York Distribution Center",
        "description": "Arrived at facility",
        "timestamp": "2025-04-07T02:15:00Z"
      }
    ]
  }
}

Receive Real-time Updates

To receive real-time notifications when parcel statuses change:

1. Create a webhook subscription for tracking_parcel.status_changed events
2. Configure your endpoint to receive HTTP POST requests
3. Process the webhook payload to update your systems

For details on setting up webhooks, see the Webhooks Guide.

Best Practices

For optimal tracking experience:

1. Always validate tracking numbers: Ensure tracking numbers follow the format expected by the shipping provider
2. Use descriptive references: Make tracking parcels easy to identify with meaningful references
3. Handle exceptions: Implement proper handling for delivery exceptions
4. Provide recipient information: Complete recipient details can help troubleshoot delivery issues
5. Configure webhooks: Set up webhooks for real-time status updates rather than polling the API

Troubleshooting

Common issues with tracking parcels:

1. Invalid tracking number: Ensure the tracking number format is correct for the selected shipping provider
2. Inactive shipping channel: Verify that the associated shipping channel is validated and active
3. Delayed updates: Some shipping providers update tracking information with a delay
4. Mismatched carrier: Make sure you're using the correct shipping channel for the tracking number
5. Rate limits: Be aware of rate limits when polling for tracking updates