Send tracking events to Shippit

Providing timely and accurate tracking updates is essential for a good customer experience. You are responsible for sending tracking events to Shippit as shipments move through your network.

You can send tracking events using one of two methods:

CSV file uploads for batch updates
Webhooks for real-time updates

Shippit strongly recommends that you use webhooks, as they provide a much better customer experience.

CSV file upload

To use this method, your system generates a single CSV file containing all new tracking events and uploads it to the Shippit SFTP server. You must upload a tracking file as soon as you have updated tracking information, to maintain service level agreements (SLAs).

Host name: carrier-sftp.shippit.com
Directory: /inbound/tracking/
Filename: Tracking_YYYY-MM-DD_HHMMSS.csv

For example, a tracking file generated on 29 August, 2025, is named Tracking_2025-09-05_113343.csv.

When Shippit have processed the tracking CSV file, it’s moved to the processed folder on the SFTP server.

The tracking CSV file

Column Heading	Description	Example
`status`	The short code representing the tracking event. For a complete list, see the Status Codes section.	`IT`
`labelNumber`	Unique tracking number for this consignment	`CARR00098765`
`timestamp`	Date and time of the event, in ISO 8601 UTC format	`2025-09-05T01:33:43Z`
`reason`	A human-readable description of the tracking event	`In Transit`

Webhooks

This is the preferred method of sending tracking event updates.

To use this method, send updates to Shippit in real-time as soon as a tracking event occurs in your system. For each tracking event, send an HTTP POST request with a JSON payload to Shippit’s webhook endpoint:

Endpoint URL: https://app.shippit.com/carrier-gateway/external/tracking/<carrierCode>
HTTP Method: POST

Use these headers:

Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_TOKEN>

Shippit provides your secret token during setup.

The webhook payload must use this JSON format:

{
  "status": "completed",
  "labelNumber": "00065432101000066",
  "timestamp": "2025-06-01T12:00:00+10:00",
  "reason": "Delivered successfully",
}

Field	Type	Description	Example
`status`	String	The short code representing the tracking event. For a complete list, see the Status Codes section.	`IT`
`labelNumber`	String	Unique tracking number for this consignment	`CARR00098765`
`timestamp`	String	Date and time of the event, in ISO 8601 UTC format	`2025-09-05T01:33:43Z`
`reason`	String	A human-readable description of the tracking event	`In Transit`

Handling responses and retries

When you send the webhook payload, Shippit responds with an HTTP status code to indicate success or failure:

Success: Shippit responds with HTTP 202 Accepted to acknowledge receipt.
Errors: For any other status (4xx or 5xx), treat the request as failed. Implement a retry policy with exponential back off for failed requests.

For a list of error codes, along with remedies to try, see the Troubleshooting section.

Status codes

Both CSV and webhook methods use the same set of status codes:

Code	Description
`awaiting_collection`	Awaiting collection
`awaiting_drop_off`	Awaiting drop off
`cancelled`	Cancelled
`completed`	Completed
`completing`	Completing
`customs_awaiting_payment`	Customs awaiting payment
`customs_failed`	Customs failed
`customs_on_hold`	Customs on hold
`damaged`	Damaged
`delivery_attempted`	Delivery attempted
`delivery_failed`	Delivery failed
`ignore`	Ignore
`in_transit`	In transit
`in_transit_with_onforwarder`	In transit with onforwarder
`insufficient_address`	Insufficient address
`lost`	Lost
`parcel_completed`	Parcel completed
`partially_completed`	Partially completed
`pickup_failed`	Pickup failed
`ready_for_pickup`	Ready for pickup
`return_booked`	Return booked
`return_booking_failed`	Return booking failed
`return_requested`	Return requested
`returned_to_sender`	Returned to sender
`untrackable`	Untrackable
`with_customs`	With customs
`with_driver`	With driver