Quickstart
Your first tracker in 5 minutes
Test mode is free forever and returns realistic sample data — you can verify the whole integration before spending a cent.
Get a test API key
Create your developer account — a test key (sk_shipyu_test_…) is issued the moment your email is verified. Copy it from the console Keys page. No credit card required.
Create a tracker
One POST. Omit carrier and Shipyu auto-detects it from the tracking number.
curl https://shipyu.com/api/v1/trackers \
-H "Authorization: Bearer sk_shipyu_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"tracker": {
"tracking_code": "9400111899223033005436",
"carrier": "USPS"
}
}'You get back a normalized tracker — the same fields, the same status vocabulary, on every carrier:
{
"id": "trk_abc123",
"object": "Tracker",
"mode": "test",
"tracking_code": "9400111899223033005436",
"status": "in_transit",
"carrier": "USPS",
"tracking_details": [
{
"object": "TrackingDetail",
"message": "Arrived at USPS Regional Facility",
"status": "in_transit",
"datetime": "2024-01-16T14:30:00Z",
"tracking_location": { "city": "Denver", "state": "CO", "country": "US" }
}
]
}Read it back any time
curl https://shipyu.com/api/v1/trackers/trk_abc123 \
-H "Authorization: Bearer sk_shipyu_test_YOUR_KEY"Live-mode trackers keep polling the carrier and update automatically; test-mode trackers return stable sample timelines.
Receive webhooks
Register an endpoint in the console (Webhooks page) and Shipyu delivers tracker.created and tracker.updated events — HMAC-signed, with 5 retries on failure. Verify signatures like this:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyShipyuSignature(secret, body, header) {
// Header: "t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>"
const match = header.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
if (!match) return false;
const expected = createHmac("sha256", secret)
.update(`${match[1]}.${body}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(match[2], "hex");
return a.length === b.length && timingSafeEqual(a, b);
}Use the console's "send test event" button to fire a synthetic delivery at your endpoint any time.
Go live
Add a payment method in the console, switch to your live key, and you are in production. Usage-based pricing: $0.020 per tracker, falling with volume — see pricing.