ShipStack API reference

Authentication

Create keys in Settings → API (requires the API keys permission and a plan with API access). Send the key as a bearer token. The full key is shown once; ShipStack stores only its SHA-256 hash.

curl https://shipstack.app/api/v1/orders \
  -H "Authorization: Bearer ss_live_…"

• ss_live_… — full access within the key's scopes.
• ss_test_… — same data, but POST /labels only works for test-mode (sandbox) shipments, so a test integration can never spend money.

Scopes

Errors

Every error uses the same envelope. Branch on type, show message, and include request_id (also in the X-Request-Id header) when contacting support.

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "parcel.weight_oz: Too small: expected number to be >0",
    "param": "parcel.weight_oz",
    "request_id": "req_4Zb1yS0a9vQhJx2m"
  }
}

Idempotency

Send an Idempotency-Key header (any unique string up to 255 characters, e.g. a UUID) on POST requests to retry safely after a timeout. It is required for POST /labels. Keys are scoped to your organization and endpoint.

• • Same key + same body → the original status and body are replayed, with Idempotent-Replayed: true.
• • Same key + different body → 409 idempotency_key_reused.
• • Same key while the first request is still running → 409 idempotency_request_in_progress; retry shortly.
• • 5xx responses aren't stored, so retrying with the same key re-attempts the request.

curl -X POST https://shipstack.app/api/v1/labels \
  -H "Authorization: Bearer ss_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0b1c1e-2a47-4f7e-9d0e-6f1f6b0b7a21" \
  -d '{"shipment_id":"…","rate_id":"…","label_format":"PDF_4x6","confirmed_amount_cents":842}'

Pagination

List endpoints return newest first in a list envelope. Pass limit (1–100, default 25) and, for the next page, starting_after set to the previous page's next_cursor.

{
  "object": "list",
  "data": [ { "id": "…", "object": "order", … }, { "id": "8c2e…", "object": "order", … } ],
  "has_more": true,
  "next_cursor": "8c2e…",
  "url": "/api/v1/orders"
}

Rate limits

120 requests per 60 seconds per API key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Over the limit you get 429 rate_limit_error with Retry-After.

Webhooks

Add HTTPS endpoints in Settings → API. Each event is POSTed as JSON with a ShipStack-Signature header. Respond 2xx within 10 seconds; anything else is retried with exponential backoff (30 s, 2 m, 8 m, 32 m, ~2 h, then every ~6 h) for 8 attempts, after which the delivery is marked dead. You can retry from the dashboard. Deduplicate on the event id — retries reuse it.

ShipStack-Signature: t=1760000000,v1=<hex HMAC-SHA256 of "1760000000.<raw body>">
ShipStack-Event-Id: evt_…
ShipStack-Event-Type: shipment.label_purchased

{
  "id": "evt_…",
  "object": "event",
  "type": "shipment.label_purchased",
  "created": 1760000000,
  "data": { "object": { "id": "…", "object": "shipment", … } }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact request body string (don't re-serialize parsed JSON)
export function verifyShipStack(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}