Mock shipping & tracking API — fake shipments and tracking events, no signup

You're building the "Where's my order?" page: a status badge, a tracking timeline, an ETA, maybe a map pin. You need shipping-shaped JSON — and every real shipping API puts an account between you and your first fake response. Verified with plain unauthenticated curls, September 2026:

• Shippo — api.goshippo.com answers {"detail":"Authentication credentials were not provided."}. Test tokens exist, but only after dashboard signup.
• EasyPost — {"error":{"code":"UNAUTHORIZED","message":"Unable to access the requested resource, authorization failed."}}. Test-mode keys live behind an account.
• ShipEngine — {"errors":[{"error_code":"unauthorized","message":"Access denied."}]}. Sandbox keys require registration.
• 17TRACK — {"code":401,…"Access token is invalid."}. Even the tracking-only API wants a token first.

Those test modes exist to verify their integration — carrier accounts, label purchases, rate quotes. If all you need today is a stateful shipping-shaped API for a frontend, a demo, a workshop, or CI, this guide builds one in a single paste: hosted, CORS-open, HTTPS, no account, no key.

1. A shipping-shaped mock in one paste

BASE=https://mockbird.mockbird.workers.dev
P=$(curl -s -X POST $BASE/api/projects -H 'content-type: application/json' \
     -d '{"name":"fake-shipping","blank":true}')
PID=$(echo $P | sed 's/.*"id": *"\([^"]*\)".*/\1/')
KEY=$(echo $P | sed 's/.*"adminKey": *"\([^"]*\)".*/\1/')

curl -s -X POST $BASE/api/projects/$PID/resources -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{
  "name":"shipments",
  "fields":[
    {"name":"tracking_number","type":"uuid"},
    {"name":"carrier","type":"oneOf","values":["usps","ups","fedex","dhl_express"]},
    {"name":"service","type":"oneOf","values":["ground","two_day","overnight","international"]},
    {"name":"status","type":"oneOf","values":["pre_transit","in_transit","out_for_delivery","delivered","exception"]},
    {"name":"origin_city","type":"city"},
    {"name":"destination_city","type":"city"},
    {"name":"eta","type":"futureDate"},
    {"name":"weight_oz","type":"number"}
  ],
  "seed":8
}'

curl -s -X POST $BASE/api/projects/$PID/resources -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{
  "name":"tracking_events",
  "fields":[
    {"name":"shipmentId","type":"oneOf","values":[1,2,3,4,5,6,7,8]},
    {"name":"status","type":"oneOf","values":["pre_transit","in_transit","out_for_delivery","delivered","exception"]},
    {"name":"location","type":"city"},
    {"name":"description","type":"sentence"},
    {"name":"ts","type":"pastDate"}
  ],
  "seed":30
}'

Two tricks worth stealing: shipmentId is a numeric oneOf [1..8], so every seeded scan points at a shipment that actually exists — no dangling joins — and the vocabulary is the industry's own (pre_transit, out_for_delivery, exception are the states Shippo/EasyPost use), so a later swap to real data touches less code.

A shipment looks like this (live output, IDs will differ):

curl "https://mockbird.mockbird.workers.dev/m/<PID>/shipments/2"

{
  "id": 2,
  "tracking_number": "b5f3448b-d1e1-43c3-8c26-2a26370bfb5b",
  "carrier": "dhl_express",
  "service": "ground",
  "status": "delivered",
  "origin_city": "Nairobi",
  "destination_city": "Zagreb",
  "eta": "2026-12-10T01:46:33.772Z",
  "weight_oz": 206
}

2. The queries a tracking page actually makes

# the tracking timeline for one shipment (json-server-style nested route)
curl "$BASE/m/$PID/shipments/2/tracking_events"

# look a shipment up by its tracking number (exact-match field filter)
curl "$BASE/m/$PID/shipments?tracking_number=b5f3448b-d1e1-43c3-8c26-2a26370bfb5b"

# every delivered shipment / every exception to alert on
curl "$BASE/m/$PID/shipments?status=delivered"
curl "$BASE/m/$PID/shipments?status=exception"

# newest scans first, joined to their shipment
curl "$BASE/m/$PID/tracking_events?sortBy=ts&order=desc&limit=5&_expand=shipment"

Range filters compose too — ?ts_gte=2026-08-01 for "scans since August", ?weight_oz_gte=160 for heavy parcels. Need CSV for a spreadsheet demo? ?mock_format=csv&select=carrier,status,eta returns the same list as RFC-4180 CSV.

3. It's stateful — play the carrier

The real test of a tracking UI is change: a new scan arrives, the status flips, the timeline grows. These are real writes, visible to every subsequent read:

# a new carrier scan comes in…
curl -s -X POST $BASE/m/$PID/tracking_events -H 'content-type: application/json' \
  -d '{"shipmentId":2,"status":"delivered","location":"Zagreb",
       "description":"Delivered, signed by resident","ts":"2026-09-16T04:00:00Z"}'
# → {"id": 31, …}

# …and the shipment itself flips to delivered
curl -s -X PATCH $BASE/m/$PID/shipments/2 -H 'content-type: application/json' \
  -d '{"status":"delivered"}'

curl "$BASE/m/$PID/shipments/2/tracking_events"   # timeline now includes scan 31

4. A public /track/:number endpoint

Carrier tracking pages accept any number in the URL. One custom route gives you the same shape — templated per request, no resource needed:

curl -s -X POST $BASE/api/projects/$PID/routes -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{
  "method":"GET","path":"/track/:number",
  "body":{"tracking_number":"{{params.number}}","carrier":"usps",
          "status":"in_transit","checked_at":"{{now}}"}
}'

curl "$BASE/m/$PID/track/9405511899223197428490"

{
  "tracking_number": "9405511899223197428490",
  "carrier": "usps",
  "status": "in_transit",
  "checked_at": "2026-09-16T03:47:05.208Z"
}

5. Simulate what carriers actually do: flake

Real tracking endpoints rate-limit, time out, and 503 at peak season — exactly what your retry/backoff and stale-data UI need to survive. Deterministically:

# first two polls fail, third succeeds — assert your retry logic rides it out
curl -i "$BASE/m/$PID/shipments/2?mock_seq=503,503,200"

# a slow carrier: 2 seconds before the response
curl "$BASE/m/$PID/track/TEST123?mock_delay=2000"

# peak-season chaos: 30% of requests randomly fail
curl "$BASE/m/$PID/tracking_events?mock_chaos=0.3"

mock_seq is per-client and resettable — full recipes in testing loading & error states.

6. Webhooks — the carrier-push stand-in

EasyPost and Shippo push tracking updates to your server by webhook; so does Mockbird. Register a URL and every created/updated/deleted record fires a signed POST (X-Mockbird-Signature: sha256=…, HMAC of the raw body) — so the code path that reacts to "package moved" runs for real in dev and CI:

curl -s -X PUT $BASE/api/projects/$PID/webhook -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{"url":"https://your-app.example.com/hooks/tracking"}'

# then play the carrier: POST a tracking_event (section 3) → your endpoint
# receives a signed tracking_events.created delivery

Verification snippet and the queryable delivery log in sending test webhooks.

Shipping-API concern → Mockbird

Honest comparison — where the real providers win

• They do the actual shipping. Label purchase, rate shopping across carriers, address validation, customs forms, manifests — none of that can be mocked into existence. The moment your code buys a label, you need a real provider and their test mode.
• Their test modes verify their integration. If you're debugging an EasyPost webhook signature or a Shippo rate response, their sandbox is the truth; our records are your own approximation of shipping-shaped data.
• Real tracking data is theirs. 17TRACK and carrier APIs return what the carrier actually scanned. A mock can only return what you told it — perfect for UI states, useless for a real parcel.

The clean split: Mockbird for the order-tracking frontend, demos, portfolio projects, and CI. A real provider the moment code touches labels, rates, or real parcels. They compose — point your app at the mock in dev via an env base URL, the real API in prod.

Notes & limits

• Building the rest of the shop too? The fake e-commerce API guide sets up products/orders/customers with one preset — add these two resources to the same project and orders can reference shipments.
• Want responses that mirror a real provider byte-for-byte? Record one test-mode call and replay it — see mocking third-party APIs.
• This mock should never see real addresses or real tracking numbers of actual customers — it's for fake data by design.
• Free tier: 10,000 requests/project/day, 1,000 records/resource. It's a mock — don't point production at it.

Create yours

The paste block in section 1 is the whole setup — or open the dashboard and click it together. The same project also serves GraphQL, exports OpenAPI + TypeScript types, and ejects to db.json anytime — no lock-in.