Developers
One request, every carrier.
Create a shipment as a draft, then submit it to the carrier you choose with the same request, whichever it is. Signed webhooks tell you about every change.
The API in one example
Every request carries an API key in the Authorization header. Submitting to a carrier needs an Idempotency-Key, so repeating the same request never creates the shipment twice.
- The answer is
202at once, with the create operation. Itsstatecarries the outcome:requested, thensucceededorfailed. - Follow the outcome by webhook, or ask for the operation itself.
- An unknown request field is rejected; ignore any new response field.
POST /v1/shipments/{id}/submit
Authorization: Bearer sfk_…
Idempotency-Key: order-1042-submit
Content-Type: application/json
{"carrier": {"code": "smsa", "service": "standard"}}
202 Accepted
{"shipment": {"id": "…", "reference": "ORDER-1042", "status": "draft", …},
"operation": {"id": "…", "kind": "create", "state": "requested", …}}Webhooks and their signatures
Each delivery is a POST to your URL, signed with the endpoint's secret (whsec_…). Verify it before you act on it:
- Compute
HMAC-SHA256with the whole secret (includingwhsec_) as the key, over<t>.<body>: the value oft, a dot, then the raw body as it arrived. - Accept the delivery if any
v1entry equals the result. There are two during a rotation. - Reject the delivery if
tis more than 5 minutes old.
idis the same in every redelivery of an event, so deduplicate by it.- Events are not ordered. Ignore an event whose
shipment.versionis lower than one you applied. - Any
2xxanswer is success. Anything else is retried after 1 minute, 5, 30, and further apart for up to 3 days.
POST https://your-store.example/webhooks
Content-Type: application/json
ShipFlow-Event-Id: 0196…
ShipFlow-Event-Type: shipment.status_changed
ShipFlow-Signature: t=1763287200,v1=5f1c…import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, header, rawBody) {
const parts = header.split(',').map((p) => p.split('='));
const t = parts.find(([k]) => k === 't')?.[1];
if (!t || Date.now() / 1000 - Number(t) > 300) return false;
const want = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return parts.some(([k, v]) => {
if (k !== 'v1') return false;
const got = Buffer.from(v, 'hex');
return got.length === want.length && timingSafeEqual(got, want);
});
}The full reference
The full API documentation and the OpenAPI spec will be published here soon. Until then, write to us for a copy.