Trace’s sandbox returns fixed scenarios without making live carrier requests or consuming monthly lookup quota. It still requires authentication and remains subject to request rate limits. Use it to test your application’s response handling, not to measure carrier coverage.
A good test suite separates response shape, authorization, failure handling and live acquisition. One successful delivered fixture proves only that one fixture works; it does not prove your retry behavior or customer isolation.
Make the fixture explicit
Call the dedicated sandbox endpoint and keep its result labeled as sample data. Do not use plausible-looking fake tracking numbers against the live endpoint to simulate success. For an unattended test environment, use a separate test account and store its credential as a server secret.
cURL · deterministic fixture
curl https://api.traceapi.dev/v1/sandbox/track \
-H "Authorization: Bearer $TRACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scenario":"unknown_timezone"}'Cover the states that change the interface
The fixed scenarios exercise different display decisions. Keep a snapshot of the expected behavior rather than assuming every scenario has an estimate, location or UTC timestamp.
| Scenario | What to verify |
|---|---|
| pending | No fabricated movement or delivery date. |
| in_transit | Readable event history and current state. |
| out_for_delivery | Current status visible without promising a delivery hour. |
| delivered | Delivered state without inventing a recipient signature. |
| exception | Actionable explanation without claiming a guaranteed remedy. |
| unknown_timezone | Null UTC preserved; local scan text explicitly labeled. |
Add failures outside the successful scenario endpoint
Use local HTTP fixtures to simulate a 401, a monthly-quota error, a 429 with Retry-After, a 503 and a transport timeout. A sandbox success cannot simulate all of those infrastructure conditions. Verify that retry loops have an attempt budget and never expose your secret key.
For webhooks, test signature verification using raw bytes, duplicate event IDs and out-of-order shipment revisions. Keep those tests local or on a controlled receiver; do not send test notifications to customer endpoints.
Finish with a small authorized live sample
After fixtures pass, test known parcels with real scans for the carriers you intend to support. Record whether each result is live, cached, stale or failed and retain its request ID. Repeat deliberately after an outage rather than assuming a catalog entry guarantees acquisition.
The free plan starts with 200 successful monthly lookups. Fixture tests do not spend that allowance, but successful live and cached checks do. Use the sandbox for repeated UI development and reserve real lookups for source qualification.
Common questions
Can sandbox results prove a shipment was delivered?
No. They are illustrative fixtures. Only a live or previously verified source observation can describe a real shipment, and it must retain its verification context.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.