Skip to content
ShipFlow
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 202 at once, with the create operation. Its state carries the outcome: requested, then succeeded or failed.
  • 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:

  1. Compute HMAC-SHA256 with the whole secret (including whsec_) as the key, over <t>.<body>: the value of t, a dot, then the raw body as it arrived.
  2. Accept the delivery if any v1 entry equals the result. There are two during a rotation.
  3. Reject the delivery if t is more than 5 minutes old.
  • id is the same in every redelivery of an event, so deduplicate by it.
  • Events are not ordered. Ignore an event whose shipment.version is lower than one you applied.
  • Any 2xx answer 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…
Verifying in Node.js
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.

Contact us