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

The file must follow these rules:

• The first line is the header row, exactly status,labelNumber,timestamp,reason, in that order.
• Use LF line endings.
• Don't quote or escape values. A comma inside a value splits the row.
• Every status value must come from the Status Codes section. One unrecognised value rejects the whole file.

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": "in_transit",
  "labelNumber": "00093275101964204450",
  "timestamp": "2025-09-05T01:33:43Z",
  "reason": "In transit"
}

Identify the event with either field:

• labelNumber applies the event to one package
• consignmentNumber applies the event to the whole consignment

Send one or the other, not both.

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 confirm the request was received. Shippit validates the payload after sending the response, so a 202 confirms that the request arrived, not that Shippit recorded the event. During testing, check the order in Shippit to confirm the event landed.
• 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: