Getting Started

Welcome to ShipShim. This guide walks you from zero to your first successful API call.

Try it without signing up

Want to kick the tires first? The live demo on the home page hits a public, unauthenticated endpoint that's rate-limited to 10 requests per minute per IP. Use it to verify the response shape and carrier detection before you commit to creating an account.

Quick start

1. Create an account

Sign up for a free account. The Free tier includes 100 API calls per month — enough for development and small projects.

2. Generate an API key

After logging in, go to API Keys in the customer portal and click Create New Key. Give it a descriptive name like Production or Local dev.

Important: The full key is displayed once, on creation. Copy it immediately and store it somewhere safe — the portal will only show the prefix afterwards.

3. Make your first 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"}'

4. Handle the response

A successful response includes the resolved carrier, the direct tracking URL, a confidence score, and the full list of carriers that matched (sorted by confidence):

{
  "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"
    }
  ]
}

confidence is a calibrated 0–100 estimate that the top carrier really issued this number, derived from the number's own structure — a UPU S10 country code, a distinctive prefix, or a verified check digit (UPS, USPS, FedEx). It is not a country-of-origin bias: 97–99 means a structural signal pins one carrier, 88–92 a single distinctive format, and ≤70 (with ambiguous: true) means several carriers share the format. The matches array lists the candidate carriers, best-first.

Many carriers use plain numeric tracking numbers, so a number alone genuinely can't always be pinned to one carrier. When that happens the response is flagged ambiguous: true (still HTTP 200) with the confidence capped at 70 — pass a carrier or country hint to resolve it. See the API reference for the exact shape.

Authentication

Every authenticated endpoint accepts your API key in one of three ways:

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

Bearer header is preferred — query-string keys may land in access logs.

Plans and rate limits

Plan Monthly calls
Free 100
Starter 10,000
Pro 100,000

Quota is checked atomically before the controller runs and counted whether the call succeeded, returned not_found, or matched ambiguously. Validation errors (HTTP 422) do not count — your reservation is released when the request fails input validation.

When the monthly limit is reached, further calls return 429 Too Many Requests with the current limit and used counters in the body.

Next steps