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

| Milestone | Description | |-----------|-------------| | pending | Tracking created, no events yet | | info_received | Carrier received shipment info | | in_transit | Package in transit | | out_for_delivery | Out for delivery today | | delivered | Successfully delivered | | failed_attempt | Delivery attempt failed | | available_for_pickup | Ready for pickup | | exception | Problem with delivery | | expired | Tracking expired |

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

Common Courier Codes

| Carrier | Code | |---------|------| | DHL Express | dhl | | DHL Germany | dhl-de | | DPD Germany | dpd-de | | DPD UK | dpd-uk | | FedEx | fedex | | UPS | ups | | USPS | us-post | | China Post | china-post | | Deutsche Post | deutsche-post | | Hermes Germany | hermes-de | | GLS | gls |

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:

Loop through active deliveries
Fetch results for each trackerId
Compare status with lastStatus
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]"
Update lastStatus and lastCheck

Adding a Delivery

When human says "track this package: ABC123":

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"}'

Save to memory:

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

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

| Code | Meaning | |------|---------| | 401 | Invalid API key | | 404 | Tracker not found | | 429 | Rate limit exceeded | | 422 | Invalid tracking number format |