Developer Documentation

API Reference

The Warewiser REST API gives you programmatic access to inventory, receiving, transfers, delivery, and analytics — secured with OAuth 2.0 and available on Standard and Enterprise plans.

Base URL

api.warewiser.com/v1

Protocol

HTTPS · REST · JSON

Auth

OAuth 2.0 Bearer

Version

v1 (stable)

Get API Access →

Jump to

Overview Authentication Rate Limits & Errors API Endpoints Webhooks Integrations

Section 01

Overview

All API requests are made over HTTPS. The API speaks JSON — every request body must be application/json, and every successful response returns JSON.

Secure by default

Every request requires a valid Bearer token. Tokens are scoped to specific modules.

Idempotent writes

Pass X-Idempotency-Key on any POST or PATCH. Safe to retry on network failure.

Versioned & stable

The /v1 path is stable. Breaking changes are introduced only with a new version prefix.

Versioning

The API version is set by the path prefix. The current stable version is /v1. When a future version ships, both versions run in parallel for a minimum 12-month deprecation window. The response header WW-API-Version echoes the version that handled each request.

Pagination

List endpoints return cursor-based pagination. Pass ?limit= (max 200, default 50) and ?cursor=from the previous response's next_cursor field. When has_more: false, you have reached the end.

json — paginated response envelope

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "cur_1a2b3c4d",
  "total_count": 4821
}

Section 02

Authentication

Warewiser uses OAuth 2.0 Client Credentials grant. Your integration obtains a short-lived access token using a Client ID and Client Secret generated in the Warewiser Admin console.

Navigate to Settings → API Access → New Application to generate credentials. Tokens expire after 60 minutes — refresh before expiry using your credentials again.

Step 1 — Request a token

bash

curl -X POST https://api.warewiser.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type":    "client_credentials",
    "client_id":     "ww_client_xxxxxxxxxxxxxxxx",
    "client_secret": "ww_secret_xxxxxxxxxxxxxxxx",
    "scope":         "inventory:read transfers:write"
  }'

Step 2 — Token response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type":   "Bearer",
  "expires_in":   3600,
  "scope":        "inventory:read transfers:write"
}

Step 3 — Authenticate every request

bash

curl https://api.warewiser.com/v1/inventory/bins \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Never expose your Client Secret in client-side code or public repositories. Rotate credentials immediately if compromised — use the Admin console under Settings → API Access → Revoke.

Token scopes

Scope	Access granted
`inventory:read`	Read bins, SKUs, stock positions, adjustments
`inventory:write`	Create and confirm inventory adjustments
`receiving:read`	Read ASNs, GRNs, discrepancy reports
`receiving:write`	Create and confirm ASNs and GRNs
`transfers:read`	Read transfer orders and pallet history
`transfers:write`	Create, execute, and cancel transfers
`delivery:read`	Read delivery orders and trip details
`delivery:write`	Create orders, dispatch trips, record POD
`analytics:read`	Read KPIs, heatmap data, saved reports
`webhooks:manage`	Create and delete webhook subscriptions
`admin:read`	Read users, roles, and audit log
`admin:write`	Create and update users (requires admin role)

Section 03

Rate Limits & Errors

Limits are applied per API application (client_id) on a rolling 60-second window. When a limit is exceeded the API returns 429 Too Many Requests.

Use the Retry-After response header (seconds) before retrying. Implement exponential backoff for production integrations.

Plan limits

Category	Standard	Enterprise	Burst
Inventory reads	300 / min	1,000 / min	2× for 60 s
Transaction writes	100 / min	500 / min	1.5× for 30 s
Report generation	10 / hr	100 / hr	—
Bulk import	5 / hr · 10k rows	50 / hr · 100k rows	—
Webhook deliveries	—	Unlimited inbound	—

HTTP status codes

Status	Meaning	Common cause
`200 OK`	Request succeeded	Standard GET / PATCH response
`201 Created`	Resource created	Successful POST
`204 No Content`	Success, no body	DELETE or accepted async action
`400 Bad Request`	Invalid payload	Missing required field, wrong type
`401 Unauthorized`	Missing or invalid token	Token expired or malformed
`403 Forbidden`	Insufficient scope	Token lacks required scope
`404 Not Found`	Resource does not exist	Wrong ID or resource deleted
`409 Conflict`	State conflict	Duplicate idempotency key with different body
`422 Unprocessable`	Validation failed	Business rule violation
`429 Too Many Requests`	Rate limit exceeded	Slow down and respect Retry-After
`500 Internal Error`	Server fault	Transient — retry with backoff
`503 Service Unavailable`	Maintenance or overload	Contact support

Error response format

All 4xx and 5xx responses include a machine-readable JSON body.

json

{
  "error": {
    "code":       "VALIDATION_ERROR",
    "message":    "The field 'quantity' must be a positive integer.",
    "field":      "quantity",
    "request_id": "req_8f3kd92ms"
  }
}

Always log the request_id — include it when contacting support so we can trace the exact request through our systems.

Section 04

API Endpoints

All endpoints are relative to https://api.warewiser.com/v1. Required headers on every request:

bash

Authorization: Bearer <token>
Content-Type: application/json

Authentication

POST

/auth/token

Exchange client credentials for a Bearer token (60-min expiry)

POST

/auth/refresh

Refresh a token using client credentials before expiry

DELETE

/auth/token

Revoke an active token immediately

Inventory

GET

/inventory/bins

List bin positions with current occupancy and available capacity

GET

/inventory/bins/{binId}

Retrieve a single bin with stock detail and occupancy history

GET

/inventory/skus

List SKU catalogue — UOM, weight, dimensions, velocity class

GET

/inventory/skus/{skuId}/stock

Current stock positions for a SKU across all bins

POST

/inventory/adjustments

Submit a manual stock adjustment (requires inventory:write scope)

GET

/inventory/adjustments

List adjustments filtered by date range or operator

Receiving (ASN)

POST

/receiving/asns

Create an Advanced Shipping Notice from an external system or ERP

GET

/receiving/asns

List ASNs — filter by status: pending | in_progress | completed | discrepancy

GET

/receiving/asns/{asnId}

ASN detail with expected vs received quantities per line

PATCH

/receiving/asns/{asnId}

Update ASN metadata or cancel a pending ASN

POST

/receiving/asns/{asnId}/confirm

Confirm GRN and post goods receipt to inventory

GET

/receiving/grns

List Goods Receipt Notes with date and operator filters

Transfers

POST

/transfers

Initiate a transfer order between bins, zones, or warehouse sites

GET

/transfers

List transfers — filter by status, zone, operator, or date

GET

/transfers/{transferId}

Transfer detail including lines, status, and event timeline

POST

/transfers/{transferId}/execute

Confirm transfer execution (operator scan-to-confirm flow)

POST

/transfers/{transferId}/cancel

Cancel a pending or in-progress transfer

GET

/transfers/pallets/{palletId}

Current bin location and full movement history for a pallet

Delivery & Dispatch

POST

/delivery/orders

Create a delivery order from a pick wave or external sales order

GET

/delivery/orders

List delivery orders — filter by status, carrier, or date

GET

/delivery/orders/{orderId}

Delivery order detail with line items and fulfilment status

POST

/delivery/orders/{orderId}/dispatch

Dispatch a delivery order — generates manifest and shipping label

GET

/delivery/trips

List delivery trips with vehicle, driver, and route details

POST

/delivery/trips/{tripId}/pod

Record proof-of-delivery for a completed trip

Heatmap & Analytics

GET

/heatmap/zones

Zone-level activity data — touch frequency and throughput volume by time window

GET

/heatmap/bins

Bin-level activity heatmap data for a configurable time range

GET

/analytics/kpis

Real-time KPIs — received, transferred, dispatched, exceptions

GET

/analytics/reports

List saved report definitions and their last-run status

POST

/analytics/reports/{reportId}/run

Trigger a report run and receive an async download URL

Administration

GET

/admin/users

List users — includes role, status, and last-active timestamp

POST

/admin/users

Create a user and assign a role (requires admin:write scope)

PATCH

/admin/users/{userId}

Update a user's profile, role, or status (active / suspended)

GET

/admin/audit-log

Query the immutable audit log — filter by operator, module, or date

GET

/admin/sites

List warehouse sites and their configuration

Section 05

Webhooks

Webhooks let you receive real-time notifications when events occur in Warewiser — without polling the API. Register a public HTTPS endpoint and Warewiser will POST a signed JSON payload within seconds.

Managing subscriptions

POST

/webhooks/subscriptions

Subscribe to one or more event types with a target HTTPS endpoint URL

GET

/webhooks/subscriptions

List active webhook subscriptions for this API application

DELETE

/webhooks/subscriptions/{id}

Remove a subscription — deliveries to this endpoint stop immediately

GET

/webhooks/events

List recent delivery attempts with HTTP status codes and response bodies

Subscription request

bash

curl -X POST https://api.warewiser.com/v1/webhooks/subscriptions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://your-app.com/webhooks/warewiser",
    "events": ["grn.created", "transfer.completed", "delivery.dispatched"],
    "secret": "your_signing_secret"
  }'

Payload structure

json

{
  "id":         "evt_9k2m3p4q",
  "event":      "transfer.completed",
  "created_at": "2026-01-15T10:23:45Z",
  "data": {
    "transfer_id":  "trn_abc123",
    "from_bin":     "A-01-04",
    "to_bin":       "C-05-02",
    "quantity":     120,
    "operator_id":  "usr_xyz789",
    "completed_at": "2026-01-15T10:23:40Z"
  },
  "api_version": "v1"
}

Signature verification

Every delivery includes a WW-Signature header — an HMAC-SHA256 of the raw request body signed with your subscription secret. Always verify before processing.

typescript

import crypto from "crypto";

function verifyWebhook(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry behaviour

Warewiser retries failed deliveries (non-2xx or timeout) up to 5 times using exponential backoff: 30 s, 5 min, 30 min, 2 hr, 8 hr. After the fifth failure the subscription is marked degraded and you receive an email alert. Subscriptions with no successful delivery in 72 hours are automatically disabled.

Event catalogue

Event	Trigger
`grn.created`	A Goods Receipt Note is created on ASN confirmation
`grn.discrepancy_raised`	A quantity discrepancy is flagged during receiving
`asn.cancelled`	An ASN is cancelled before confirmation
`transfer.created`	A new transfer order is initiated
`transfer.completed`	A transfer is confirmed by operator scan
`transfer.cancelled`	A transfer is cancelled mid-execution
`delivery.order_created`	A new delivery order is created
`delivery.dispatched`	A delivery order is dispatched with manifest
`delivery.pod_recorded`	Proof of delivery is captured for a trip
`inventory.adjustment_confirmed`	A manual inventory adjustment is posted
`cycle_count.variance_raised`	Cycle count variance exceeds threshold
`alert.triggered`	A configured smart alert fires
`user.created`	A new user account is created
`user.suspended`	A user account is suspended by admin

Section 06

Integrations

Warewiser ships with certified integrations for the most common ERP and inventory platforms — all maintained by the Warewiser engineering team.

SAP Business One

Certified

Bi-directional sync for Purchase Orders, GRNs, Item Master, Delivery Orders, and Inventory Adjustments. Real-time webhooks for PO and Sales Order events; 15-minute scheduled sync for Item Master and Business Partner.

Zoho Inventory

Certified

Sync incoming purchase orders, post GRNs and delivery confirmations back to Zoho. Supports Zoho Inventory, Zoho Books, and Zoho Commerce simultaneously.

Custom ERP / REST

OpenAPI

Use the full REST API with any ERP or OMS that can make HTTP calls. Download the OpenAPI 3.1 specification and import directly into Postman, Insomnia, or your code generator.

Postman Collection

Free

Pre-built Postman collection with all endpoints, example bodies, and environment variables for API key management. Import in one click and run your first request in under a minute.

Need a connector for a platform not listed here? Contact hello@warewiser.com — our integration team evaluates requests quarterly.

Ready to build?

Get your API credentials

API access is available on Standard and Enterprise plans. Talk to us and we'll provision your Client ID and Secret within one business day.

Request API Access Talk to an Engineer