API Reference

Base URL

https://shipshim.com/api/v1

The production API is at shipshim.com. If you're self-hosting, substitute your own deployment URL — the path layout is identical.

Authentication

All authenticated endpoints accept your API key three ways. Use whichever fits your client.

Authorization header (recommended)

Authorization: Bearer YOUR_API_KEY

X-API-Key header

X-API-Key: YOUR_API_KEY

Query parameter

?api_key=YOUR_API_KEY

Keys are stored hashed; ShipShim cannot recover a lost key. Generate a new one from the customer portal if you lose access to the original.

Endpoints

POST /track

Resolve a tracking number to a carrier and a direct tracking URL.

Authentication: required.

Request body

Example request

curl -X POST https://shipshim.com/api/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "country": "US"
  }'

Response: success (200)

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "country": "US",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "confidence": 97,
  "matches": [
    {
      "carrier": "UPS",
      "country": "US",
      "confidence": 97,
      "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    }
  ]
}

Response: ambiguous (200 with ambiguous: true)

Many carriers use plain numeric tracking numbers with no check digit or distinctive prefix, so a number alone genuinely can't always be pinned to one carrier. Rather than guess, ShipShim returns the most likely carrier flagged ambiguous: true, caps the confidence at 70, and lists the candidates in matches. Status is still 200. Supply a carrier or country hint to resolve it.

{
  "tracking_number": "123456789012",
  "carrier": "FedEx",
  "country": "US",
  "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=123456789012",
  "confidence": 50,
  "ambiguous": true,
  "message": "Multiple carriers use this tracking-number format. Showing the most likely match. Pass `country` (e.g. US/DE) or `carrier` to disambiguate.",
  "matches": [
    {
      "carrier": "FedEx",
      "country": "US",
      "confidence": 50,
      "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=123456789012"
    },
    {
      "carrier": "DHL Germany",
      "country": "DE",
      "confidence": 45,
      "tracking_url": "https://www.dhl.de/de/privatkunden/dhl-sendungsverfolgung.html?piececode=123456789012"
    }
  ]
}

Pass carrier or country on the next call to disambiguate.

Response: not found (404)

No carrier pattern matched the number.

{
  "error": "not_found",
  "message": "No carrier found for this tracking number."
}

This still consumes one quota call — pattern matching ran, it just didn't find anything.

POST /demo/track

Public, unauthenticated endpoint used by the homepage demo card.

Authentication: none required. Rate limit: 10 requests per minute per IP. Excess requests return 429.

Accepts the same body shape as POST /track and returns the same response shape. Usage is attributed to the internal demo account and does not affect your quota — but the strict per-IP throttle makes it unsuitable for production use.

curl -X POST https://shipshim.com/api/demo/track \
  -H "Content-Type: application/json" \
  -d '{"tracking_number": "1Z999AA10123456784"}'

GET /health

Lightweight liveness probe.

Authentication: none required. This endpoint is served by nginx in production and never enters the Laravel framework — it's safe to hit from external uptime monitors at high frequency.

curl https://shipshim.com/api/v1/health

Returns 200 OK with the text body OK.

Error responses

401 Unauthorized

API key missing or invalid (or the key has been revoked).

{
  "error": "unauthorized",
  "message": "API key is required. Include it in the Authorization header as \"Bearer YOUR_API_KEY\""
}

403 Forbidden

Account is suspended. Contact support.

{
  "error": "account_suspended",
  "message": "Your account has been suspended. Please contact support."
}

422 Unprocessable Entity

The request body failed validation (e.g. tracking_number missing or too long, carrier exceeds 100 chars, country exceeds 10 chars).

{
  "message": "The tracking number field is required.",
  "errors": {
    "tracking_number": ["The tracking number field is required."]
  }
}

Validation failures do not consume quota — the reservation made at authentication is released when the controller returns 422.

429 Too Many Requests

For authenticated /track: monthly call limit exceeded. Upgrade the plan or wait until the next billing period.

{
  "error": "rate_limit_exceeded",
  "message": "Monthly API call limit exceeded. Please upgrade your plan.",
  "limit": 100,
  "used": 100
}

For /demo/track: per-IP rate limit (10/min) exceeded — Laravel's standard throttle response.

500 Internal Server Error

An unexpected server-side error. Includes a Sentry-trackable reference if persistent.

HTTP status codes