Connect a WMS / Warehouse System

Which parts of the WMS flow exist in the API today, and which are coming soon:

Your workspace plan must include apiAccess (otherwise calls return 402). Create a key via Cockpit → Settings → API & Webhook → New API Key. Sufficient granular scopes for WMS: orders:read and webhooks:manage (add products:read, shipping:read if needed). Following least privilege, select only what you need. The raw key (sk_live_…) is shown only once; store it securely.

Send every request to the base URL with your API key in the X-API-Key header. The key is never sent in the body or a query parameter.

Base: https://api.stokzone.com/api/v1/web-api/v1
Header: X-API-Key: sk_live_xxxxxxxxxxxx

Pull orders with pagination: filter by platform and status; page with limit (max 200) and offset. The response includes items, total, page and page_size; orders are sorted by order_date descending.

curl -H "X-API-Key: $KEY" \
  "https://api.stokzone.com/api/v1/web-api/v1/orders?status=Created&platform=trendyol&limit=200&offset=0"

Note: for resumable incremental pulls, use the `since` cursor below — `limit/offset` paging shifts when a new order arrives in between and skips the record at the boundary. To capture changes in real time use webhooks (below); for bulk reconciliation, do a full scan with offset.

`limit/offset` paging shifts when a NEW order arrives in between, and the record at the page boundary is skipped — without you noticing. For resumable pulls use `since`: store `next_since` and `next_since_id` from the response and send them back on the next call.

# 1) ilk cagri — imlecsiz
curl -H "X-API-Key: $KEY" ".../orders?limit=200"

# 2) yanittaki next_since + next_since_id ile devam et
curl -H "X-API-Key: $KEY" ".../orders?limit=200&since=2026-08-24T19:02:31%2B00:00&since_id=ord_123"

# yanit:
# { "items": [...], "next_since": "...", "next_since_id": "...", "has_more": true }

`since_id` is required: several orders can share the same `updated_at` (a bulk sync writes them at once). Sending `since` alone skips the ones that land on a page boundary within that group.

The cursor means "the record CHANGED", not "its status changed": an order reappears whenever it is updated for any reason. This is deliberate — delivering twice beats skipping silently. Make your processing idempotent.

Fetch an order's detail (including shipping and address) and its items (SKU, barcode, quantity, price). The order detail lets you read the tracking_number and tracking_url that Stokzone knows.

curl -H "X-API-Key: $KEY" ".../orders/{order_id}"
curl -H "X-API-Key: $KEY" ".../orders/{order_id}/items"

The warehouse notifies Stokzone when an order ships. This is a TRIGGER: it writes the status and fetches carrier and tracking number from the pull endpoint.

POST https://api.stokzone.com/api/v1/webhooks/wms/fulfillment
X-WMS-Signature: t=<unix>,v1=<hex>      # HMAC_SHA256(sir, "<t>.<HAM govde>")

{
  "olay": "order.fulfilled",
  "inbound_order_id": "...",   # varsa BIREBIR eslesme anahtari
  "source": "stokzone",
  "external_ref": "...",       # yoksa ikincil anahtar
  "status": "shipped",
  "shipped_at": "2026-08-25T10:00:00Z"
}

A signature is required: `X-WMS-Signature: t=<unix>,v1=<hex>`, signing `"<t>.<RAW body>"`. Do not parse and re-serialize the body — key order changes and the signature will not match. `t` is replay protection; timestamps outside ±5 minutes are rejected. If the signing secret is not configured, the endpoint accepts nothing.

Matching is ORDERED: `inbound_order_id` is used when present, otherwise `source`+`external_ref`. If neither is present the order does not belong to the integrator and the event is skipped. Because `external_ref` is unique only per business, a match against several records is REJECTED — refusing beats writing to the wrong order.

Tracking number and carrier are NOT in the webhook body. A partial shipment can leave in several parcels, each with its own tracking number; squeezing them into one field would lose the rest. They come from the `shipments[]` list on the pull endpoint.

Subscribe to order.created and order.updated events; your WMS endpoint is triggered on new or changed orders. This reduces the need for continuous polling.

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://wms.example.com/hooks/stokzone","events":["order.created","order.updated"]}' \
  "https://api.stokzone.com/api/v1/web-api/v1/webhooks"

Pushing the WMS "shipped + tracking number" back to Stokzone (fulfillment push) is not yet available. When this capability is added, this section will be updated with the real endpoint. For now, status updates flow from the Stokzone panel or your existing marketplace integration.