FAQ
Answers for developers building with Trace.
The short version: keep your API key server-side, use one tracking endpoint, listen for signed webhooks, and keep your customer-facing tracking flow simple.
What does Trace do?
Trace turns a tracking number into a normalized shipment status, likely carrier, event timeline, cache metadata, and webhook-ready updates through one API.
How fast can I make my first tracking request?
Create an account, verify your email, generate a trc_live key, and send a POST request to /v1/track. An uncached lookup may take longer because it reads third-party source pages.
Should I call Trace from my frontend?
No. Keep live API keys on your server. Call Trace from your backend, serverless function, worker, or private integration layer.
How do webhooks work?
Add an endpoint in the dashboard and choose the events you want. Trace sends an HMAC-signed JSON event after a fresh, uncached tracking lookup or a test delivery. Successful lookups also register active shipments for best-effort background refreshes while the worker is enabled; update timing and delivery are not guaranteed.
How often should I check the same shipment?
Trace caches recent lookups, so repeated requests stay fast. For active shipments, polling every few hours is usually enough; delivered shipments should stop being polled.
What carriers does Trace support?
Trace accepts codes for 80+ carriers, but automatic detection currently covers selected number formats, not the whole catalog. You can provide a carrier code for an ambiguous or unrecognized number. A listed code is not a guarantee of live events; lookup results depend on available, verifiable upstream sources.
What happens if a carrier has no new scan?
If Trace has a recent verified result, it can return that cached state with a last-checked time. If no source provides verifiable dated events, Trace returns a 503 error rather than treating missing data as a new pending scan.
How do plans and limits work?
Plans are based on monthly lookup volume, request rate, and support needs. You can view current usage, manage your plan, and handle invoices from the dashboard.
Can I use Trace for customer-facing order tracking?
Yes. Trace is designed for order status pages, support dashboards, delivery notifications, internal operations tools, and post-purchase workflows.