API docs
Everything you need to add shipments, look them up, and keep them updated from your own system.
Creating a shipment
Create a shipment once it actually exists. Only add a delivery date if you have one, and change the status when something really happens. Here's what a basic shipment looks like:
{
"order_reference": "ORDER-123",
"carrier": "Carrier name",
"tracking_number": "Carrier or internal reference",
"status": "created",
"estimated_delivery_at": "2026-10-08T18:00:00Z"
}Statuses
You can use created, processing, shipped, in_transit, out_for_delivery, delivered, exception, and cancelled. Pick the one that matches what's actually happened. Please don't move a shipment forward just because its delivery date has passed.
Looking up a shipment
Send a tracking number, or an order number and email if the store supports that. You'll get back the same info a customer would see on the tracking page. It's not a full order API, so you won't get customer or payment details.
POST https://hhgjtpdbccaqthtjykoc.supabase.co/functions/v1/shipment-lookup
Authorization: Bearer {public_lookup_anon_jwt}
apikey: {public_lookup_anon_jwt}
Content-Type: application/json
{ "identifier": "SL-your-tracking-reference" }
// Or, for supported order lookup
{ "orderNumber": "ORDER-123", "email": "checkout-email" }The public key in this request only lets you look things up. It can't read or change anyone's private shipment data.
Adding and updating shipments
The business console writes to the Supabase Data API using the signed-in user's access token. Each account can only read and write its own shipments. If you're using a service key, keep it on your server.
POST https://hhgjtpdbccaqthtjykoc.supabase.co/rest/v1/shipments
apikey: {project_publishable_key}
Authorization: Bearer {signed_in_user_access_token}
Content-Type: application/json
Prefer: return=representation
{
"order_reference": "ORDER-123",
"carrier": "Carrier name",
"status": "created"
}A few ground rules
- Only send an update once it's actually happened, and send it once. Keep the original timestamp.
- No new update? Leave the timeline alone. Don't fill gaps with guesses.
- If your system is down, return an error. Don't say the shipment doesn't exist.
- Nothing moves forward automatically. Refreshing just fetches the latest saved data.
- Future or scheduled stops never show up as completed in the timeline.
- Delivery dates stay estimates until there's a real update.
Tracking links can be shared
Treat tracking links like any shipping email link. Don't put customer emails, payment info, API keys, or internal notes in them, and only send them to the person expecting the package. Your API keys and tracking links are separate, so you can rotate keys without breaking any links.