Build with the ShipTastic API.

Authentication

Create an API key in the app (Account → Developer). The full key is shown once — store it securely and send it as a Bearer token on every request. Keys are scoped to your workspace, work only on /api/v1, and can be revoked anytime.

curl https://shiptastictracking.com/api/v1/account \
  -H "Authorization: Bearer stk_live_your_key_here"

Test mode (sandbox)

Tick “Test key (sandbox)” when you create a key. A stk_test_ key lets you build your whole integration for free: it returns deterministic mock data, never spends credits, and never returns 402. Scenario references drive the mock response:

A test track also fires a matching mock webhook to your test endpoints — so you can verify delivery and signatures end to end without waiting for a real shipment to move. Switch to a stk_live_ key for real tracking.

Rate limits

Up to 120 requests per minute per key. Over the limit you get 429 rate_limited — back off and retry. Live tracking is additionally metered against your plan credits.

Response format

Every response uses the same envelope:

// success
{ "ok": true, "data": { … } }

// error
{ "ok": false, "error": { "code": "payment_required", "message": "…" } }

Track a container or B/L

Billable. Tracks a container number (ISO 6346) or Bill of Lading / Sea‑Waybill and returns the live vessel position, status, milestones and ETA. A new reference spends one credit; re‑tracking a reference you already track is free; a reference with no carrier data is not charged.

curl https://shiptastictracking.com/api/v1/track/MSCU1234567 \
  -H "Authorization: Bearer stk_live_…"

{
  "ok": true,
  "data": {
    "reference": "MSCU1234567",
    "tracking": {
      "container": "MSCU1234567",
      "current_status": "In transit",
      "eta": "2026-10-21",
      "count": 7,
      "trace": [ { "event": "Vessel departed", "location": "Shanghai", "time": "…" }, … ]
    }
  }
}

If your allowance is spent you get 402 payment_required with a details object on how to top up or upgrade.

List & read shipments

The shipments you have tracked (free).

Full detail for a shipment you already track (free; 404 not_tracked if it isn’t in your list — use /track first).

Account usage

{ "ok": true, "data": { "plan": "max", "included_per_month": 150, "used_this_period": 42, "remaining": 108 } }

Alerts

List your alert rules.

Create a rule on a container you already track (omit reference to alert on any tracked container). Conditions: any_update, delayed, arrived.

curl -X POST https://shiptastictracking.com/api/v1/alerts \
  -H "Authorization: Bearer stk_live_…" -H "Content-Type: application/json" \
  -d '{"reference":"MSCU1234567","condition":"delayed","recipient":"ops@yourco.com"}'

Webhooks

Enterprise. Register one or more https endpoints and ShipTastic POSTs a signed JSON event whenever one of your tracked shipments changes. Manage them in Account → Developer or over the API:

curl -X POST https://shiptastictracking.com/api/v1/webhooks \
  -H "Authorization: Bearer stk_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhooks/shiptastic","label":"prod"}'
// -> { "ok": true, "data": { "id":"wh_…", "secret":"whsec_…" } }  (secret shown once)

Event types

Delivery & payload

POST https://your-app.com/webhooks/shiptastic
ShipTastic-Event: shipment.updated
ShipTastic-Delivery: evt_…
ShipTastic-Signature: t=1696570000,v1=<hex hmac-sha256>

{
  "id": "evt_8f2a…",
  "type": "shipment.updated",
  "created": 1696570000,
  "data": { "reference":"MSCU1234567", "status":"in_transit", "delayed":false,
            "vessel":"EXAMPLE VESSEL", "eta":"2026-10-21", "last_updated":"…" }
}

Respond 2xx to acknowledge. On any other status or a timeout we retry with exponential backoff (up to 6 attempts). Events can arrive more than once — treat them idempotently by id.

Verify the signature

The ShipTastic-Signature header is t=<unix ts>,v1=<hex>. Recompute HMAC‑SHA256("<t>.<raw body>", secret) and compare in constant time; reject if the timestamp is too old.

import hmac, hashlib
signed   = f"{t}.{raw_body}"                 # raw bytes, unparsed
expected = hmac.new(secret.encode(), signed.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, v1):
    reject()

Errors

API reference & OpenAPI

Browse the full interactive API reference — every endpoint, parameter and response, rendered from the spec. Or grab the machine‑readable OpenAPI 3.0 spec to import into Postman, Insomnia or your codegen:

https://shiptastictracking.com/api/v1/openapi.json