Ship24

Ship24 Tracking Skill

Track parcels worldwide using the Ship24 API. Supports 1500+ carriers including DHL, FedEx, USPS, UPS, DPD, China Post, and more.

Setup

Get API Key: https://dashboard.ship24.com/integrations/api-keys

Store credentials in ~/.config/ship24/credentials.json:

{
  "api_key": "apik_xxx"
}

Or use environment variable: SHIP24_API_KEY

API Base

https://api.ship24.com/public/v1

Auth Header: Authorization: Bearer YOUR_API_KEY

Quick Reference

Create a Tracker

curl -X POST "https://api.ship24.com/public/v1/trackers" \
  -H "Authorization: Bearer $SHIP24_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1234567890",
    "courierCode": ["dpd-de"],
    "destinationCountryCode": "DE"
  }'

Response:

{
  "data": {
    "tracker": {
      "trackerId": "abc-123-def",
      "trackingNumber": "1234567890",
      "isSubscribed": true,
      "isTracked": true,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  }
}

Get Tracking Results

curl "https://api.ship24.com/public/v1/trackers/$TRACKER_ID/results" \
  -H "Authorization: Bearer $SHIP24_API_KEY"

Response:

{
  "data": {
    "trackings": [{
      "tracker": { "trackerId": "abc-123" },
      "shipment": {
        "statusCode": "in_transit",
        "statusMilestone": "in_transit",
        "originCountryCode": "CN",
        "destinationCountryCode": "DE"
      },
      "events": [{
        "status": "Parcel is in transit",
        "occurrenceDatetime": "2026-01-16T14:30:00",
        "location": "Frankfurt, DE",
        "statusCode": "in_transit"
      }]
    }]
  }
}

Create Tracker and Get Results (One Call)

curl -X POST "https://api.ship24.com/public/v1/trackers/track" \
  -H "Authorization: Bearer $SHIP24_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1234567890"
  }'

List All Trackers

curl "https://api.ship24.com/public/v1/trackers?page=1&limit=25" \
  -H "Authorization: Bearer $SHIP24_API_KEY"

Search by Tracking Number (No Tracker)

curl -X POST "https://api.ship24.com/public/v1/tracking/search" \
  -H "Authorization: Bearer $SHIP24_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumber": "1234567890"}'

Status Codes

Status Categories: pending, info_received, in_transit, out_for_delivery, delivery, exception

Common Courier Codes

Full list: GET /public/v1/couriers

Heartbeat Integration

Track deliveries in your heartbeat routine. Store state in your memory file:

{
  "deliveries": [
    {
      "tracking": "1234567890",
      "carrier": "DPD",
      "description": "New laptop",
      "ship24TrackerId": "abc-123-def",
      "lastStatus": "in_transit",
      "lastCheck": "2026-01-16T10:00:00Z"
    }
  ],
  "ship24ApiKey": "apik_xxx"
}

Check routine:

1. Loop through active deliveries
2. Fetch results for each trackerId
3. Compare status with lastStatus
4. Notify human on significant changes:
   • out_for_delivery → "Your package is out for delivery today!"
   • delivered → "Package delivered!" + remove from list
   • exception → "Delivery problem with [description]"
5. Update lastStatus and lastCheck

Adding a Delivery

When human says "track this package: ABC123":

1. Create tracker:

curl -X POST "https://api.ship24.com/public/v1/trackers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumber": "ABC123"}'

2. Save to memory:

{
  "tracking": "ABC123",
  "ship24TrackerId": "<trackerId from response>",
  "description": "Package from human",
  "lastStatus": "pending",
  "added": "2026-01-16"
}

3. Confirm: "Added tracking for ABC123. I'll let you know when there are updates."

Tips

• Auto-detect carrier: Ship24 usually detects the carrier automatically. Only specify courierCode if you know it.
• Destination country: Helps with detection. Use ISO 2-letter codes (DE, US, CN).
• Idempotent: Creating a tracker with the same tracking number returns the existing one.
• Rate limits: Check your plan limits at dashboard.ship24.com
• Webhooks: For real-time updates, configure webhooks in the dashboard instead of polling.

Error Handling

Links

• Dashboard: https://dashboard.ship24.com
• API Docs: https://docs.ship24.com
• OpenAPI Spec: https://docs.ship24.com/assets/openapi/ship24-tracking-api.yaml