The STOWAGE.ID API

Quickstart

1. 1

   Create a key in the dashboard → API & webhooks (Business or Enterprise plan) and pick the scopes you need.

2. 2

   Send requests to the base URL with the header Authorization: Bearer stw_live_…

3. 3

   Register a webhook endpoint for plan.completed and quote.received, then verify its signature.

Base URL

https://api.stowage.id/v1/ext

Authentication

Every request uses an organisation API key in the Authorization header. Keys are shown once and stored as a SHA-256 hash — keep them on your server, never in front-end or mobile code.

Authorization: Bearer stw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Rate limits & quotas

Rate limits apply per key over a sliding 1-minute window; call quotas per organisation per calendar month. Exceeding the rate limit → 429 with a Retry-After header; quota used up or a plan without API → 402.

Synchronous solves are limited to 500 units per request; larger loads use Advanced Optimisation in the Studio (413 response).

Error format

All errors share one shape; HTTP codes: 400 invalid input, 401 bad key, 402 plan/quota, 403 scope, 404 not found, 413 too large, 429 rate limit.

{
  "error": {
    "code": "paywall",
    "message": "Monthly API call quota exhausted",
    "paywall": { "moment": "feature", "quota": "api_calls", "limit": 10000, "used": 10000, "suggestedPlan": "enterprise" }
  }
}

Examples

curl

curl -X POST https://api.stowage.id/v1/ext/plans/solve \
  -H "Authorization: Bearer $STOWAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PO 4711",
    "space": { "code": "40HC" },
    "items": [
      { "sku": "CARTON-A", "l": 600, "w": 400, "h": 400, "kg": 12, "qty": 40 },
      { "sku": "CRATE-B", "l": 1200, "w": 800, "h": 1000, "kg": 300, "qty": 6, "stackable": false }
    ],
    "save": true
  }'

curl "https://api.stowage.id/v1/ext/ports?q=Tanjung%20Priok" \
  -H "Authorization: Bearer $STOWAGE_API_KEY"

TypeScript SDK

Dependency-free TypeScript client (fetch + WebCrypto) for Node 18+, Deno, Bun and Cloudflare Workers. stowage-ext.ts

import { createExtClient } from './stowage-ext'; // /developers/stowage-ext.ts

const stowage = createExtClient({ apiKey: process.env.STOWAGE_API_KEY! });

const { result, plan } = await stowage.solve({
  space: { code: '40HC' },
  items: [{ sku: 'CARTON-A', l: 600, w: 400, h: 400, kg: 12, qty: 40 }],
  save: true,
});
console.log(result.utilizationPct, plan?.appUrl);

const { rfq } = await stowage.createRfq({
  title: 'Kopi ke Singapura', originLocode: 'IDTPP', destLocode: 'SGSIN', mode: 'LCL', incoterm: 'FOB',
  readyDate: '2026-12-01', planId: plan?.id, contact: { name: 'Ops', email: 'ops@example.com' },
});

Load planning simulation. Not a substitute for official weighing, VGM, the vessel loading computer, or operator approval.

Endpoint reference

Generated from the OpenAPI 3.1 specification. openapi.json

Webhooks

We POST JSON to your endpoint. Reply 2xx within 10 seconds; otherwise we retry up to 7 times over ≈ 9 hours (30 s, 2 min, 10 min, 30 min, 2 h, 6 h). Every delivery is logged in the dashboard.

Events

Verifying signatures

The Stowage-Signature header contains t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 with the endpoint secret over "<t>.<raw body>", compare it with v1 in constant time, and reject timestamps more than 5 minutes off.

Stowage-Signature: t=1767225600,v1=5f2b…c9e1

import { verifyWebhookSignature } from './stowage-ext';

// Express: app.post('/webhooks/stowage', express.raw({ type: 'application/json' }), handler)
const ok = await verifyWebhookSignature({
  secret: process.env.STOWAGE_WEBHOOK_SECRET!, // whsec_…
  body: req.body.toString('utf8'),             // RAW body, before JSON.parse
  header: req.header('Stowage-Signature'),
});
if (!ok) return res.status(400).end();
const event = JSON.parse(req.body.toString('utf8')); // { id, type, createdAt, orgId, data }

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

function verify(secret: string, rawBody: string, header: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
  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('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Kontainer.id & Logistikku.id integrations

Partners send plans to organisations that granted access (consent + scopes) using the Stowage-Integration header and a Stowage-Signature over the raw body — no API key. Shared identity only with the profile:read scope. Currently in sandbox mode.

BODY='{"title":"Booking KTR-991","space":{"code":"20GP"},"items":[{"sku":"BOX","l":1000,"w":1000,"h":1000,"kg":100,"qty":4}]}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$INTEGRATION_SECRET" -hex | sed 's/^.* //')
curl -X POST https://api.stowage.id/v1/ext/integrations/kontainer_id/plans \
  -H "Content-Type: application/json" \
  -H "Stowage-Integration: $INTEGRATION_ID" \
  -H "Stowage-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

Embeddable widget

Put a CBM calculator, mini planner and "Request a quote" button on your vendor website. Free with a "Powered by Stowage.id" link; white-label on Vendor Premium. Leads land in your vendor inbox; domains are allowlisted.

<script src="https://embed.stowage.id/v1.js" data-vendor="wdg_…" data-locale="en" async></script>

Optional attributes: data-locale="id|en" and data-target="#selector". For SPAs: window.StowageWidget.mount(el, { widget }).

Stowage.id connects users and vendors; the service contract is between the user and the vendor.

For vendors