Ship24 Integration

Ship24 Tracking API integration

Opinionated wizard: detect the project, clarify the plan, guide the implementation, verify the result.

Facts in this skill come from docs.ship24.com and the OpenAPI 3.1 spec at docs.ship24.com/assets/openapi/ship24-tracking-api.yaml. The bundled references/endpoints.md and schemas.md are generated from that spec, errors.md and rate-limits.md from the docs pages. When a detail matters (a field name, a status code, a limit), read the reference file rather than guessing:

Sibling skills: ship24-webhooks (build the receiver), ship24-couriers (courier codes and required fields), ship24-tracking-statuses (map statuses to business logic), ship24-troubleshooting (errors), ship24-node-sdk (the official ship24 npm package), ship24-track (look up one parcel now via the MCP tools).

Phase 1: Detect

Scan before asking. Use the host tool's search if there is no shell.

grep -ri "ship24" . --include=*.{js,ts,py,rb,php,go,java,cs,env,json,yaml,yml} 2>/dev/null | head -20
grep -ri "SHIP24" .env .env.local .env.example 2>/dev/null
grep -rE "express|fastify|nest|fastapi|django|flask|rails|laravel|symfony|gin|spring|aspnet" \
  package.json requirements.txt pyproject.toml Gemfile composer.json go.mod pom.xml *.csproj 2>/dev/null | head
grep -rn "webhook" . --include=*.{js,ts,py,rb,php,go,java,cs} 2>/dev/null | head
grep -rE "bull|bullmq|celery|sidekiq|rabbitmq|sqs|pubsub|kafka" \
  package.json requirements.txt pyproject.toml Gemfile composer.json go.mod 2>/dev/null | head -5

Note: existing Ship24 usage (trackers created? webhook route present?), language and framework, HTTP client in use, queue or async infrastructure, an existing public webhook route that can be extended.

If the project is Node.js or TypeScript, prefer the official SDK (npm install ship24) over hand-written HTTP calls and switch to the ship24-node-sdk skill for the implementation details.

Phase 2: Clarify

Ask only what detection could not determine, one question at a time.

1. Account and key. Does the user have a Ship24 account and API key? A free plan exists for integration and testing: dashboard.ship24.com/onboarding. Keys live under Integrations → API Keys (up to 20 active keys per account).
2. Plan type. Per-shipment (the standard product: trackers, webhooks, polling) or per-call (a separate subscription, one synchronous endpoint, no trackers)? If unsure: per-shipment is the default choice; Ship24 documents it as offering more features, faster fetching and lower overall cost.
3. Update mechanism (per-shipment only). Webhooks (Ship24 pushes updates, recommended) or polling (the app calls the API)? Webhooks need a public HTTPS endpoint. At thousands of trackers, polling stops being practical.
4. Constraints. New project or existing app? Serverless? No public URL? Multi-tenant?

Do not write code until plan type, key handling (env var) and update mechanism are settled.

Phase 3: Guide

Authentication and base URL (all plans)

• Base URL: https://api.ship24.com/public/v1
• Header on every request: Authorization: Bearer <api key> (keys look like apik_...).
• Read the key from the SHIP24_API_KEY environment variable. Never hardcode it, commit it, or ship it to a browser or mobile client: the key grants full access to the account's tracking data and quota.

# .env (never committed)
SHIP24_API_KEY=apik_your_key_here

Route by plan

Per-shipment plan

Webhook flow (recommended)

1. Build a POST endpoint that answers 2xx quickly and processes asynchronously (see ship24-webhooks).
2. Register its URL in the dashboard: Integrations → Webhooks. There is no API for this.
3. Create a tracker per shipment with POST /trackers (or up to 100 at once with POST /trackers/bulk). Store the returned trackerId.
4. Ship24 pushes every new event to the endpoint. A webhook events[] array contains only the events discovered since the last push; API responses contain the full history.

Polling flow

1. POST /trackers, store trackerId.
2. Do not poll immediately: results are not available the instant a tracker is created.
3. GET /trackers/{trackerId}/results on an interval the app chooses. Ship24 does not mandate a cadence. Longer intervals for slower shipments.
4. Stop when the tracker's isTracked is false: Ship24 has stopped tracking that shipment.

Synchronous one-shot flow

POST /trackers/track creates the tracker and returns results in the same call. The first call can take up to one minute because Ship24 queries couriers synchronously; some couriers do not support it and return results on later calls. Calling it again with the same payload returns the same tracker with fresh results.

Idempotency (verified in Ship24's implementation, see the plugin's CONTRIBUTING). POST /trackers and POST /trackers/track look up the account's trackers with the same clientTrackerId when one is sent, otherwise with the same trackingNumber, and reuse a candidate without consuming quota when shippingDate (day precision), originCountryCode, destinationCountryCode, destinationPostCode, shipmentReference, courierName, trackingUrl, settings.restrictTrackingToCourierCode and the courierCode list all match. Otherwise a new tracker is created. tracker_conflict comes back when the clientTrackerId belongs to an active tracker with a different payload, and on POST /trackers/track when the courierCode list overlaps an existing tracker's list without matching it; differentiate with shippingDate or destinationCountryCode, or resend the same payload.

Identify shipments. Tracking numbers are not unique across couriers or time. Store Ship24's trackerId. Alternatively set clientTrackerId to the app's own unique id: Ship24 validates its uniqueness across subscribed trackers and most endpoints accept ?searchBy=clientTrackerId. shipmentReference is free text, not validated for uniqueness, and returned in responses and webhooks.

Tracker creation fields (full table in references/schemas.md, tracker-create-request):

Bulk creation. POST /trackers/bulk accepts 1 to 100 items and answers 201 (the docs also list 200), 207 (partial) or an error. Its body is { status, summary, data, error } with status in success | partial | error, unlike the { data } envelope of the other tracker endpoints. Rate limit 3 requests per second.

Per-call plan

POST /tracking/search with the tracking number (plus optional courier and destination hints) fetches results synchronously from couriers. Response time can reach one minute. No tracker is created, nothing to store, no webhooks. Requires an active per-call subscription; without one the API answers no_active_subscription.

Data handling rules that bite

• Add-on fields (for example shipment.delivery.aiPredictiveDeliveryDate) are absent, not null, when the account lacks the option or Ship24 has no value. Check presence before reading.
• Event occurrenceDatetime is a logistic-date-time: local time, local time with offset, UTC, or date only. Keep it as a string; use the event order field to sort events that lack a time.
• datetime, utcOffset, hasNoTime (events) and signedBy (delivery) are deprecated. Do not build on them.
• Rate limits are per endpoint per second (most are 10 req/s, bulk 3, couriers and resend 1). Honor Retry-After on 429. Details in references/rate-limits.md.
• Error bodies are { "errors": [{ "code", "message" }], "data": null } (message optional), except the bulk endpoint's { status, summary, data, error }. Branch on code, not on the message text. Codes in references/errors.md.

Phase 4: Verify

• API key read from SHIP24_API_KEY; not in source, not in client-side code.
• trackerId (or a validated clientTrackerId) persisted for every created tracker.
• Webhook endpoint answers 2xx before processing and matches payloads on trackerId or clientTrackerId.
• Duplicate deliveries handled: deduplicate on events[].eventId.
• Polling does not start immediately, uses an interval the team chose deliberately, and stops on isTracked: false.
• 401, 403, 422, 429 (with Retry-After) and 5xx handled; error code logged.
• Add-on fields read only when present.
• Tested end to end with a Ship24 sample tracking number such as SHIP24_SAMPLE_DELIVERED_000 (see ship24-tracking-statuses for the full list).

Key links