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

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.