DocsPartner API
v1 — Stable

Partner API

External machine-to-machine API for integrating WarpWare into your systems. Push orders, query inventory, receive webhooks, and access Walter AI — all via API key.

Base URL
https://api.warpware.io/partner/v1
Auth header
Authorization: Bearer ww_live_...
Content-Type (POST/PATCH)
application/json

Overview

The WarpWare Partner API lets external systems interact with your account programmatically. All responses use a consistent { "data": ..., "meta": ... } envelope.

API Key Auth
Bearer token scoped per client
Scope-Based
read and write permissions per key
Webhooks
Push events to your endpoints with HMAC signing

Endpoints at a glance

GET/ordersread
GET/orders/statsread
GET/orders/{id}read
GET/orders/by-external/{external_id}read
GET/orders/{id}/trackingread
POST/orderswrite
POST/orders/bulkwrite
PATCH/orders/{id}write
POST/orders/{id}/cancelwrite
GET/inventoryread
POST/inventory/adjustwrite
GET/productsread
GET/shipping/ratesread
POST/exportsread
GET/exports/{id}read
GET/versionread
GET/webhooksread
POST/webhookswrite
DELETE/webhooks/{id}write
POST/webhooks/{id}/testwrite
GET/orders/{id}/timelineread
POST/shipmentswrite
GET/preorder-rulesread
POST/preorder-ruleswrite
POST/preorder-rules/{id}/releasewrite
GET/locationsread
GET/inventory/locationsread
POST/inventory/syncwrite
POST/orders/{id}/labelswrite
GET/orders/{id}/labelsread
POST/orders/simulatewrite
POST/walterread

Authentication

Every request requires an API key as a Bearer token. POST and PATCH requests also require Content-Type: application/json.

Required headers
Authorization: Bearer ww_live_a1b2c3d4e5f6...
Content-Type: application/json    # POST and PATCH only
Example
curl https://api.warpware.io/partner/v1/orders \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."

Key format

Keys follow the format ww_live_<32 hex chars>. They are shown only once at creation — store them in an environment variable, never in code.

Lost your key? Rotate it from the dashboard. Rotation revokes the old key immediately.

Scopes

readAccess all GET endpoints — orders, stats, inventory, products, tracking, webhooks
writeCreate/update orders and manage webhook registrations. Requires read scope as well.

Getting API access

API keys are created through the Connections UI — the same place you'd add a Shopify or WooCommerce integration.

  1. 1. Go to Connections → Add Integration in the WarpWare dashboard
  2. 2. Select Custom API Integration
  3. 3. Enter a name for the integration (e.g. "My ERP System")
  4. 4. Copy the generated ww_live_... key — it is shown only once

Each API integration tracks its own usage stats (total orders pushed, last active). You can have multiple integrations with separate keys. Contact us if you need help getting set up.

Rate Limits

Rate limits are enforced per API key using a fixed 60-second window. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

All endpoints200 requests / minute
POST /walter10 requests / minute

Rate limit headers

Retry-After: 42    # seconds until the window resets (on 429 responses only)

Cursor Pagination

All list endpoints support two pagination modes.

Page mode (default)

Classic offset pagination. Includes total and total_pages in the response.

GET /partner/v1/orders?page=2&per_page=50
{
  "data": [ ... ],
  "meta": { "page": 2, "per_page": 50, "total": 1234, "total_pages": 25, "client_id": "acme:east" }
}

Cursor mode

Stable keyset pagination ideal for polling integrations and large datasets. Pass after=<cursor> using the next_cursor value from the previous response. Cursor mode does not return total — use GET /orders/stats for counts.

GET /partner/v1/orders?after=eyJpZCI6IjNmYTg1Z...&per_page=50
{
  "data": [ ... ],
  "meta": {
    "per_page": 50,
    "next_cursor": "eyJpZCI6IjNmYTg1Z...",
    "has_more": true,
    "client_id": "acme:east",
    "cursor_mode": true
  }
}

When has_more is false or next_cursor is null, you've reached the end of the result set.

Orders

Query existing orders or push new ones into the pipeline.

GEThttps://api.warpware.io/partner/v1/orders

List orders with filters. Returns newest-first, max 100 per page.

Query parameters
status
stringComma-separated: pending, shipped, delivered, failed, hold
tag
stringFilter by a single order tag
external_id
stringFilter by your system's order ID
date_from
ISO 8601Orders created on or after this date
date_to
ISO 8601Orders created on or before this date
updated_since
ISO 8601Orders updated at or after this timestamp — useful for polling changes
tracking_number
stringFilter by carrier tracking number
page
integerPage number, 1-based (default: 1)
per_page
integerResults per page, max 100 (default: 50)
Example
curl "https://api.warpware.io/partner/v1/orders?status=failed&updated_since=2026-02-27T00:00:00Z" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response
{
  "data": [ { ...order object... } ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 3,
    "total_pages": 1,
    "client_id": "acme:warehouse-east"
  }
}
GEThttps://api.warpware.io/partner/v1/orders/{order_id}

Get a single order by WarpWare UUID. Returns the full order object — all fields present on the order are included in the response, not just the fields documented below.

Full order response: The order object returned is not limited to the fields shown in the example. Any field stored on the order — including route_destination_label, hold_reason, error_message, metadata, fulfillment IDs, timestamps, and more — is returned as-is. Parse the full JSON for your integration rather than relying only on documented fields.
Example
curl "https://api.warpware.io/partner/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response — order object
{ "data": {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "ORDER-1234",
  "source": "api",
  "status": "pending",
  "client_id": "acme:warehouse-east",
  "sub_client_id": "warehouse-east",
  "connection_id": null,
  "line_items": [
    { "sku": "WIDGET-RED-LG", "name": "Red Widget Large", "quantity": 2, "price": 29.99 }
  ],
  "customer_email": "[email protected]",
  "customer_name": "Jane Smith",
  "shipping_address": {
    "name": "Jane Smith",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "carrier": null,
  "tracking_number": null,
  "service_level": null,
  "api_connection_id": "connection-uuid",
  "route_destination_type": "extensiv",
  "route_destination_label": "East Coast DC",
  "route_assigned_by": "routing_rule",
  "is_held": false,
  "hold_reason": null,
  "retry_count": 0,
  "error_message": null,
  "created_at": "2026-02-27T10:00:00Z",
  "updated_at": "2026-02-27T10:00:05Z",
  "processed_at": null,
  "metadata": {}
}, "meta": {} }
GEThttps://api.warpware.io/partner/v1/orders/by-external/{external_id}

Look up an order by your source system's ID. Useful when you don't have the WarpWare UUID.

Example
curl "https://api.warpware.io/partner/v1/orders/by-external/ORDER-1234" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
POSThttps://api.warpware.io/partner/v1/orders

Push a new order into the WarpWare pipeline. Requires write scope. See Idempotency section for safe retries.

Example
curl -X POST "https://api.warpware.io/partner/v1/orders" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: my-system-uuid-1234" \
  -d '{
    "external_id": "ORDER-1234",
    "line_items": [{ "sku": "WIDGET-RED-LG", "quantity": 2, "price": 29.99 }],
    "shipping_address": {
      "name": "Jane Smith", "address1": "123 Main St",
      "city": "New York", "state": "NY", "zip": "10001"
    },
    "customer_email": "[email protected]",
    "tags": ["vip"]
  }'
Request body
{
  "external_id": "ORDER-1234",          // required — unique per account
  "line_items": [                        // required
    {
      "sku": "WIDGET-RED-LG",            // required
      "name": "Red Widget Large",        // optional
      "quantity": 2,                     // required
      "price": 29.99                     // optional
    }
  ],
  "shipping_address": {                  // required
    "name": "Jane Smith",               // required
    "address1": "123 Main St",          // required
    "address2": "Apt 4B",              // optional
    "city": "New York",                 // required
    "state": "NY",                      // required
    "zip": "10001",                     // required
    "country": "US",                    // optional, default "US"
    "phone": "555-1234"                // optional
  },
  "customer_email": "[email protected]", // optional
  "customer_name": "Jane Smith",        // optional
  "note": "Leave at door",             // optional
  "tags": ["vip", "rush"],             // optional
  "metadata": {                         // optional — arbitrary key-value JSON
    "po_number": "PO-2026-001",         //   store any custom data here
    "department": "fulfillment"         //   returned as-is on GET /orders
  },
  "source": "api"                      // optional, default "api"
}
Response — 201 Created
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "external_id": "ORDER-1234",
    "source": "api",
    "status": "pending",
    "client_id": "acme:warehouse-east",
    "created_at": "2026-02-27T10:00:00Z"
  },
  "meta": {}
}
PATCHhttps://api.warpware.io/partner/v1/orders/{order_id}

Update tracking, carrier, status, or note on an existing order. Requires write scope. Status changes trigger webhooks.

Example
curl -X PATCH "https://api.warpware.io/partner/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "tracking_number": "1Z999AA10123456784", "carrier": "UPS", "status": "shipped" }'
Request body (all fields optional)
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",        // USPS | FedEx | UPS | DHL | OnTrac | etc.
  "status": "shipped",     // shipped | delivered | hold | cancelled
  "note": "Updated by WMS",
  "metadata": { "shipped_by": "warehouse-A" }  // merged into existing metadata
}
Response
{ "data": { "id": "uuid", "updated": true }, "meta": {} }
Valid status transitions
pending / processing → shipped, hold, cancelled
shipped → delivered
hold → shipped, cancelled
delivered / cancelled → no further transitions
PATCH only accepts tracking_number, carrier, status, and note. Shipping address and line items cannot be changed via the API after an order is created. Contact support for corrections.
POSThttps://api.warpware.io/partner/v1/orders/{order_id}/cancel

Cancel a pending or held order. Cannot cancel orders that are already shipped or delivered. Idempotent — cancelling an already-cancelled order returns 200.

Request body (optional)
{ "reason": "Customer requested cancellation" }
Example
curl -X POST "https://api.warpware.io/partner/v1/orders/3fa85f64-.../cancel" \
  -H "Authorization: Bearer ww_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested cancellation"}'
Response — 200 OK
{ "data": { "id": "3fa85f64-...", "status": "cancelled", "cancelled": true }, "meta": {} }
Returns 422 if the order is already shipped or delivered. Fires order.cancelled and order.status_changed webhooks.

Bulk Orders

Push up to 100 orders in a single request. Each order is processed independently — one failure does not block the rest.

POSThttps://api.warpware.io/partner/v1/orders/bulk

Submit up to 100 orders at once. Returns HTTP 207 Multi-Status with a per-item result for every order in the batch.

Example
curl -X POST "https://api.warpware.io/partner/v1/orders/bulk" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "external_id": "ORDER-2001",
        "line_items": [{ "sku": "WIDGET-BLUE-M", "quantity": 1 }],
        "shipping_address": {
          "name": "Bob Jones", "address1": "456 Oak Ave",
          "city": "Denver", "state": "CO", "zip": "80201"
        }
      },
      {
        "external_id": "ORDER-2002",
        "line_items": [{ "sku": "GADGET-XL", "quantity": 3, "price": 49.99 }],
        "shipping_address": {
          "name": "Alice Wu", "address1": "789 Elm St",
          "city": "Seattle", "state": "WA", "zip": "98101"
        },
        "tags": ["rush"]
      }
    ]
  }'
Response — 207 Multi-Status
{
  "data": [
    {
      "external_id": "ORDER-2001",
      "status": "created",
      "id": "11111111-0000-0000-0000-000000000001",
      "created_at": "2026-02-27T15:01:00Z"
    },
    {
      "external_id": "ORDER-2002",
      "status": "duplicate",
      "message": "Order with this external_id already exists"
    }
  ],
  "meta": {
    "total": 2,
    "created": 1,
    "duplicates": 1,
    "errors": 0,
    "client_id": "acme:warehouse-east"
  }
}
Per-item status values
created — order accepted and queued
duplicate — external_id already exists; idempotent, not a failure
error — validation or server error; see message field
Always check each item's status field. The HTTP status is always 207 — even if every order failed. Max 100 orders per request; sending more returns 422.

Order Stats

Get a count of orders broken down by status. Useful for dashboards and monitoring.

GEThttps://api.warpware.io/partner/v1/orders/stats

Returns total order count and per-status breakdown. Optionally scoped to a date range.

Query parameters
date_from
ISO 8601Count orders created on or after this date
date_to
ISO 8601Count orders created on or before this date
Example
curl "https://api.warpware.io/partner/v1/orders/stats?date_from=2026-02-01" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response
{
  "data": {
    "total": 1482,
    "by_status": {
      "pending": 34,
      "processing": 12,
      "shipped": 1301,
      "delivered": 98,
      "failed": 22,
      "hold": 15
    }
  },
  "meta": { "client_id": "acme:warehouse-east" }
}

Inventory

Query real-time inventory levels synced from your connected warehouse.

GEThttps://api.warpware.io/partner/v1/inventory

List inventory levels with optional filters.

Query parameters
sku
stringExact SKU match
status
stringin_stock | low_stock | out_of_stock
search
stringPartial match on SKU or product name
updated_since
ISO 8601Only return items synced at or after this timestamp
page / per_page
integerPagination (max 100 per page)
Example
curl "https://api.warpware.io/partner/v1/inventory?status=low_stock&updated_since=2026-02-27T00:00:00Z" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response
{
  "data": [
    {
      "sku": "WIDGET-RED-LG",
      "name": "Red Widget Large",
      "quantity_available": 12,
      "quantity_on_hand": 15,
      "quantity_committed": 3,
      "warehouse": "East Coast DC",
      "status": "low_stock",
      "updated_at": "2026-02-27T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 4, "total_pages": 1 }
}
POSThttps://api.warpware.io/partner/v1/inventory/adjust

Apply a signed delta adjustment to a SKU's available quantity. Positive values add stock, negative values remove it. Rejects adjustments that would result in negative inventory.

Request body
sku
stringProduct SKU to adjust (required)
adjustment
integerSigned delta — +10 adds 10 units, -5 removes 5 (required)
warehouse
stringExtensiv facility ID — narrows to a specific location (optional)
reason
stringReason for adjustment — logged for audit purposes (optional)
Example
curl -X POST "https://api.warpware.io/partner/v1/inventory/adjust" \
  -H "Authorization: Bearer ww_live_..." \
  -H "Content-Type: application/json" \
  -d '{"sku": "WIDGET-RED-L", "adjustment": -3, "reason": "Damaged in receiving"}'
Response — 200 OK
{
  "data": {
    "sku": "WIDGET-RED-L",
    "previous_quantity": 8,
    "adjustment": -3,
    "new_quantity": 5,
    "reason": "Damaged in receiving"
  },
  "meta": {}
}
Returns 404 if SKU not found. Returns 422 if adjustment would produce negative inventory. Uses atomic SQL update to prevent race conditions.

Products

Query the product catalog synced from your connected platforms.

GEThttps://api.warpware.io/partner/v1/products

List products. Search by name or look up by exact SKU.

Query parameters
sku
stringExact SKU lookup
search
stringPartial match on name or description
updated_since
ISO 8601Only return products updated at or after this timestamp
page / per_page
integerPagination (max 100 per page)
Example
curl "https://api.warpware.io/partner/v1/products?search=widget" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response
{
  "data": [
    {
      "id": "uuid",
      "sku": "WIDGET-RED-LG",
      "name": "Red Widget Large",
      "description": "Our flagship red widget in large",
      "price": 29.99,
      "inventory_count": 142,
      "platform": "shopify",
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-27T09:15:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 }
}

Shipping Rates

Get representative carrier rate estimates for a shipment.

These are estimates only — WarpWare does not currently have a live carrier rate API connected. The response shape is stable for future live-rate integration. For accurate quotes use EasyPost, ShipStation, or your carrier directly.
GEThttps://api.warpware.io/partner/v1/shipping/rates

Get estimated carrier rates for an origin/destination pair and package weight.

Query parameters
origin_zip
stringOrigin ZIP code (required)
destination_zip
stringDestination ZIP code (required)
weight_oz
numberPackage weight in ounces (required)
length / width / height
numberDimensions in inches — enables DIM weight calculation (optional)
Example
curl "https://api.warpware.io/partner/v1/shipping/rates?origin_zip=78701&destination_zip=10001&weight_oz=32&length=12&width=8&height=6" \
  -H "Authorization: Bearer ww_live_..."
Response
{
  "data": {
    "origin_zip": "78701",
    "destination_zip": "10001",
    "weight_oz": 32,
    "billable_weight_lbs": 2.07,
    "dim_weight_lbs": 4.16,
    "rates": [
      { "carrier": "USPS", "service": "Priority Mail", "estimated_days": 3, "rate_usd": 10.75 },
      { "carrier": "UPS", "service": "UPS Ground", "estimated_days": 5, "rate_usd": 13.40 },
      { "carrier": "FedEx", "service": "FedEx Ground", "estimated_days": 5, "rate_usd": 14.10 }
    ],
    "disclaimer": "Estimates only."
  },
  "meta": {}
}

Exports

Async bulk export jobs let you pull all your data in one shot without paginating through thousands of pages. POST to create a job, then poll GET until complete. Limit: 5,000 rows per export.

POSThttps://api.warpware.io/partner/v1/exports

Create an async bulk export job. Returns 202 Accepted immediately — poll the job URL until status is complete.

Request body
resource
stringorders | inventory | products (required)
filters
objectKey-value filters — orders support status, date_from, date_to (optional)
Example
curl -X POST "https://api.warpware.io/partner/v1/exports" \
  -H "Authorization: Bearer ww_live_..." \
  -H "Content-Type: application/json" \
  -d '{"resource": "orders", "filters": {"date_from": "2026-01-01", "date_to": "2026-01-31"}}'
Response — 202 Accepted
{
  "data": { "id": "export-uuid", "status": "pending", "resource": "orders", "created_at": "..." },
  "meta": { "poll_url": "/partner/v1/exports/export-uuid", "row_limit": 5000 }
}
GEThttps://api.warpware.io/partner/v1/exports/{id}

Poll export job status. Returns data inline when status is complete. Typical latency: 1–10 seconds.

Example
curl "https://api.warpware.io/partner/v1/exports/export-uuid" \
  -H "Authorization: Bearer ww_live_..."
Response — complete
{
  "data": {
    "id": "export-uuid",
    "resource": "orders",
    "status": "complete",
    "created_at": "...",
    "completed_at": "...",
    "count": 1247,
    "rows": [ { "id": "...", "external_id": "ORDER-1042", "status": "shipped", ... } ]
  },
  "meta": {}
}
Poll every 2 seconds until status is complete or error. For real-time data use the list endpoints with cursor pagination.

Tracking

Get carrier tracking and fulfillment status for a specific order.

GEThttps://api.warpware.io/partner/v1/orders/{order_id}/tracking

Returns tracking number, carrier, service level, and fulfillment timestamps.

Example
curl "https://api.warpware.io/partner/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6/tracking" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
Response
{
  "data": {
    "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "external_id": "ORDER-1234",
    "status": "shipped",
    "extensiv_status": "Shipped",
    "carrier": "UPS",
    "tracking_number": "1Z999AA10123456784",
    "service_level": "UPS Ground",
    "shipped_at": "2026-02-26T14:22:00Z",
    "estimated_delivery": "2026-02-28T23:59:00Z",
    "delivered_at": null
  },
  "meta": {}
}
extensiv_status is the raw status string from the downstream warehouse system. status is WarpWare's normalized value.

Idempotency

POST /orders supports an optional X-Idempotency-Key header. If you send the same key within 24 hours, the API returns the original response instead of creating a duplicate order — making it safe to retry on network failures.

curl -X POST "https://api.warpware.io/partner/v1/orders" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: my-system-uuid-abc123" \
  -d '{ ... }'
Use any unique string — a UUID, your internal order ID, or a hash works well
Keys are scoped to your account — the same key string used by two different accounts is independent
Keys expire after 24 hours — after that, using the same key creates a new order normally
If you omit the header, the API falls back to checking external_id uniqueness and returns 409 on duplicates

Webhooks

Register HTTPS endpoints to receive real-time event notifications. WarpWare delivers events with HMAC-signed payloads and retries on failure.

Event types

order.status_changedFired on any order status change
order.shippedOrder marked as shipped (includes tracking info)
order.deliveredOrder confirmed delivered
order.failedOrder failed processing
order.heldOrder placed on hold
webhook.testManually triggered test event
There is no order.created event. To sync new orders into your system, poll GET /orders?updated_since= on a schedule — this covers both new orders and status changes that webhooks may have missed.
POSThttps://api.warpware.io/partner/v1/webhooks

Register a new webhook endpoint. The secret is returned only once — store it immediately. Max 10 active endpoints per account.

Example
curl -X POST "https://api.warpware.io/partner/v1/webhooks" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/webhooks/warpware",
    "events": ["order.shipped", "order.failed"]
  }'
Request body
{
  "url": "https://your-system.com/webhooks/warpware",  // required, must be HTTPS
  "events": ["order.shipped", "order.failed"]           // required, see event types above
}
Response — 201 Created
{
  "id": "endpoint-uuid",
  "url": "https://your-system.com/webhooks/warpware",
  "events": ["order.shipped", "order.failed"],
  "active": true,
  "created_at": "2026-02-27T10:00:00Z",
  "last_delivery_at": null,
  "last_delivery_status": null,
  "failure_count": 0,
  "secret": "a1b2c3d4e5f6..."   // shown ONCE — store this securely
}
The secret is only returned at registration. You need it to verify incoming payloads. If lost, delete and re-register the endpoint.
GEThttps://api.warpware.io/partner/v1/webhooks

List all registered webhook endpoints for your account. Secret is never returned here.

Example
curl "https://api.warpware.io/partner/v1/webhooks" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
DELETEhttps://api.warpware.io/partner/v1/webhooks/{endpoint_id}

Remove a webhook endpoint. All pending and undelivered events for this endpoint are cancelled.

Example
curl -X DELETE "https://api.warpware.io/partner/v1/webhooks/endpoint-uuid" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."
POSThttps://api.warpware.io/partner/v1/webhooks/{endpoint_id}/test

Send a test event to verify your endpoint is reachable and your signature verification is working.

Example
curl -X POST "https://api.warpware.io/partner/v1/webhooks/endpoint-uuid/test" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..."

Delivery headers

WarpWare POSTs to your URL with these headers:

Content-Type: application/json
X-WarpWare-Signature: sha256=<hex>
X-WarpWare-Event: order.shipped
X-WarpWare-Delivery: <event-uuid>
User-Agent: WarpWare-Webhooks/1.0

Payload shape

{
  "id": "event-uuid",
  "event": "order.shipped",
  "timestamp": "2026-02-27T10:05:00Z",
  "data": {
    "id": "order-uuid",
    "external_id": "ORDER-1234",
    "status": "shipped",
    "carrier": "UPS",
    "tracking_number": "1Z999AA10123456784",
    ...
  }
}

Verifying the signature

Always verify the X-WarpWare-Signature header using the secret from registration to confirm the payload came from WarpWare.

Python
import hmac, hashlib

def verify_signature(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# In your webhook handler:
body = request.get_data()  # raw bytes
sig  = request.headers["X-WarpWare-Signature"]
if not verify_signature(WEBHOOK_SECRET, body, sig):
    return 401
Node.js
const crypto = require('crypto');

function verifySignature(secret, body, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// In your webhook handler:
const body = req.rawBody;  // must be raw bytes, not parsed JSON
const sig  = req.headers['x-warpware-signature'];
if (!verifySignature(WEBHOOK_SECRET, body, sig)) {
  return res.status(401).send('Invalid signature');
}

Retry behavior

If your endpoint returns a non-2xx status or times out, WarpWare retries with exponential backoff:

Attempt 1Immediate
Attempt 210 seconds later
Attempt 31 minute later
After 3 failuresEvent marked as failed
After 10 consecutive endpoint failuresEndpoint auto-disabled

Respond with a 2xx status as quickly as possible. If processing takes longer than a few seconds, queue the event and respond immediately — a slow or timed-out response counts as a failure and will be retried.

Order Timeline

Get the full event history for an order — every status change, rule evaluation, hold, push attempt, and error. Essential for debugging stuck or failed orders.

GEThttps://api.warpware.io/partner/v1/orders/{'{id}'}/timeline

Get order event history

Query Parameters
limit — Max events to return (default 50, max 200)
Response
{
  "data": {
    "order_id": "a1b2c3d4-...",
    "external_id": "#1234",
    "event_count": 6,
    "events": [
      {
        "source": "push",
        "type": "push_success",
        "component": "ExtensivAPIConnector",
        "message": "Order pushed to Extensiv (ID: 1293672)",
        "details": { "extensiv_order_id": "1293672", "duration_ms": 450 },
        "occurred_at": "2026-03-30T14:30:00Z"
      },
      {
        "source": "audit",
        "type": "status_changed",
        "component": "RuleEvaluationWorker",
        "message": "Status changed: pending to ready",
        "details": { "old_status": "pending", "new_status": "ready" },
        "occurred_at": "2026-03-30T14:29:55Z"
      },
      {
        "source": "lifecycle",
        "type": "received",
        "component": "OrderIngestionService",
        "message": "Order received from shopify",
        "details": {},
        "occurred_at": "2026-03-30T14:29:50Z"
      }
    ]
  }
}

You can use either the WarpWare UUID or the external_id as the order identifier. Events are returned newest-first.

Shipments

Push warehouse-level shipments directly into WarpWare. Unlike orders, shipments represent items already allocated to a specific warehouse.

POSThttps://api.warpware.io/partner/v1/shipments

Push a shipment into the pipeline

Request Body
{
  "external_id": "SHIP-014191",
  "source": "erp",
  "warehouse_id": "6",
  "ship_to": {
    "name": "IEH QUANTA",
    "address1": "9330 CORPORATE DRIVE",
    "city": "SELMA",
    "state": "TX",
    "zip": "78154",
    "country": "US",
    "phone": "8003288378",
    "email": "[email protected]"
  },
  "line_items": [
    { "sku": "3041-80", "quantity": 2, "description": "Specimen Cup", "uom": "CS" }
  ],
  "carrier": "FedEx",
  "service": "Ground",
  "note": "Handle with care"
}
Response (201)
{
  "data": {
    "id": "e5a92a16-5bfd-4765-9920-334c646eea68",
    "external_id": "SHIP-014191",
    "status": "pending",
    "message": "Shipment ingested and queued for processing"
  }
}

Pre-Orders

Manage pre-order hold rules. Orders containing matching SKUs are automatically held until released.

GEThttps://api.warpware.io/partner/v1/preorder-rules

List all pre-order rules

Response
{
  "data": [
    {
      "id": "b20a1d3d-180a-4e28-939f-e6858a40c087",
      "sku": "DWP2-PPCN85HC",
      "name": "Devil Wears Prada 2 Bucket",
      "status": "holding",
      "hold_mode": "split",
      "release_date": null,
      "orders_held_count": 12,
      "orders_released_count": 0
    }
  ]
}
POSThttps://api.warpware.io/partner/v1/preorder-rules

Create a pre-order rule

Request Body
{
  "sku": "NEW-PREORDER-SKU",
  "name": "Upcoming Product Launch",
  "hold_mode": "split",
  "release_date": "2026-05-01"
}
POSThttps://api.warpware.io/partner/v1/preorder-rules/{'{id}'}/release

Release all orders held by a rule

Response
{
  "data": {
    "rule_id": "b20a1d3d-...",
    "sku": "DWP2-PPCN85HC",
    "status": "released",
    "orders_released": 12
  }
}

hold_mode: split separates pre-order SKUs into a held child order while non-pre-order items ship immediately. hold_entire holds the entire order.

Locations

Discover physical locations across all connected platforms — Shopify stores, Extensiv facilities, Acumatica warehouses.

GEThttps://api.warpware.io/partner/v1/locations

List all locations

Query Parameters
platform — Filter by platform: shopify, extensiv, acumatica
Response
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Best Way Distribution",
      "platform": "shopify",
      "platform_location_id": "72812298393",
      "address1": "1705 Kansas Avenue",
      "city": "Kansas City",
      "state": "KS",
      "country": "US",
      "active": true,
      "is_primary": true,
      "sku_count": 187
    }
  ]
}

Inventory by Location

Get inventory levels per SKU with location awareness.

GEThttps://api.warpware.io/partner/v1/inventory/locations

Inventory levels by location

Query Parameters
sku — Filter by SKU
location_id — Filter by location ID
Response
{
  "data": [
    {
      "sku": "3041-80",
      "name": "Specimen Cup",
      "source_platform": "extensiv",
      "inventory_quantity": 150,
      "quantity_available": 142,
      "quantity_on_hand": 150,
      "quantity_committed": 8,
      "shopify_location_id": 72812298393
    }
  ]
}
POSThttps://api.warpware.io/partner/v1/inventory/sync

Trigger downstream inventory push

Response
{
  "data": {
    "message": "Queued 245 inventory updates for downstream sync",
    "queued": 245
  }
}

Shipping Labels

Attach pre-generated shipping labels to orders. Labels are automatically injected into Extensiv when the order pushes to the warehouse.

POSThttps://api.warpware.io/partner/v1/orders/{'{id}'}/labels

Attach a shipping label

Request Body
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "service_level": "Ground",
  "label_url": "https://labels.example.com/label-12345.pdf",
  "label_format": "pdf",
  "weight": 12.5,
  "weight_unit": "oz",
  "cost": 8.45,
  "currency": "USD"
}
Response (201)
{
  "data": {
    "label_id": "f1e2d3c4-...",
    "order_id": "a1b2c3d4-...",
    "external_id": "#1234",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "passed_to_extensiv": false,
    "message": "Label attached — will be injected when order pushes to Extensiv"
  }
}
GEThttps://api.warpware.io/partner/v1/orders/{'{id}'}/labels

List labels on an order

Response
{
  "data": [
    {
      "id": "f1e2d3c4-...",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "UPS",
      "service_level": "Ground",
      "label_url": "https://labels.example.com/label-12345.pdf",
      "passed_to_extensiv": true,
      "passed_to_extensiv_at": "2026-03-30T14:30:00Z"
    }
  ]
}

You can use either the WarpWare UUID or the external_id as the order identifier. Labels with label_url are injected into Extensiv via the parcel label injector API after the order is pushed.

Test Simulation

Create realistic test orders for integration testing. Orders flow through the real pipeline (rules, holds, territory) but do NOT push to the warehouse.

POSThttps://api.warpware.io/partner/v1/orders/simulate

Create test order(s)

Request Body
{
  "source": "api",
  "count": 5,
  "line_items": [
    { "sku": "TEST-SKU-001", "quantity": 2, "description": "Test Product" }
  ],
  "ship_to": {
    "name": "Test Customer",
    "address1": "123 Test St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  }
}
Response
{
  "data": {
    "created": 5,
    "failed": 0,
    "orders": [
      { "id": "...", "external_id": "TEST-20260330-a1b2c3" }
    ],
    "message": "5 test order(s) created and queued for processing"
  }
}

Test orders are tagged with TEST_ORDER and do not push to Extensiv by default. Max 100 per request.

Walter AI

Ask questions about your orders in plain English. Walter has full context of your account's data. Rate limited to 10 requests/minute.

POSThttps://api.warpware.io/partner/v1/walter

Submit a natural-language query against your order data.

Example
curl -X POST "https://api.warpware.io/partner/v1/walter" \
  -H "Authorization: Bearer ww_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "How many orders failed in the last 7 days?" }'
Request body
{
  "query": "How many orders failed in the last 7 days?",  // required
  "context": {}   // optional
}
Example queries
"How many orders shipped this week?"
"Show failed orders from the last 7 days"
"What's the status of order ORDER-1234?"
"Which SKUs have the most holds right now?"
"How many orders came in from Shopify yesterday?"
Response
{
  "data": {
    "response": "In the last 7 days, 14 orders failed. The most common error was 'SKU not found in warehouse system' (9 orders).",
    "tool_calls": [...],
    "client_id": "acme:warehouse-east"
  },
  "meta": {}
}
Walter responses are scoped to your account's data only. If Walter is unavailable or not enabled for your account, the endpoint returns 503 Service Unavailable with a descriptive error message. Contact us to confirm Walter is enabled on your account before building against this endpoint.

Version

Use the version endpoint to verify connectivity, detect deprecations, and confirm which API channel you're talking to. The X-WarpWare-API-Version response header is included on every response.

GEThttps://api.warpware.io/partner/v1/version

Returns the current Partner API version string and stability channel.

Example
curl "https://api.warpware.io/partner/v1/version" \
  -H "Authorization: Bearer ww_live_..."
Response
{
  "data": {
    "version": "2026-02-27",
    "stable": true,
    "channel": "v1",
    "note": "v1 is the current stable channel. Breaking changes will be announced and versioned."
  },
  "meta": {}
}

Errors

Standard HTTP status codes. Error responses include a detail field.

200OKRequest succeeded
201CreatedOrder or webhook endpoint created
207Multi-StatusBulk order response — check each item's status field; HTTP 207 even if all items failed
400Bad RequestMissing required fields or invalid parameter values
401UnauthorizedMissing, invalid, revoked, or expired API key
403ForbiddenKey lacks the required scope (read or write)
404Not FoundResource does not exist or belongs to a different account
409ConflictDuplicate external_id on order creation
422UnprocessableValid JSON but fails validation (e.g. missing required address fields)
429Rate LimitedToo many requests — check Retry-After header
500Server ErrorUnexpected error — contact support if it persists
503UnavailableWalter AI is not enabled or unavailable for your account

Error response format

{ "detail": "Invalid API key or key has been revoked" }

Changelog

All breaking changes are versioned. Non-breaking additions (new endpoints, new optional fields) are added without a version bump.

2026-03-04Added metadata JSONB field on orders — store arbitrary key-value data on create (POST), merge on update (PATCH), returned on all reads (GET)
2026-02-27Added POST /orders/{id}/cancel — dedicated cancel endpoint with optional reason field
2026-02-27Added POST /inventory/adjust — signed delta inventory write with atomic update
2026-02-27Added cursor-based pagination (?after=<cursor>) on orders and inventory list endpoints
2026-02-27Added POST /exports + GET /exports/{id} — async bulk export jobs (orders, inventory, products)
2026-02-27Added GET /shipping/rates — carrier rate estimates (DIM weight, multi-carrier)
2026-03-30Added GET /orders/{id}/timeline — full order event history for debugging
2026-03-30Added POST/GET /orders/{id}/labels — attach and list shipping labels for Extensiv injection
2026-03-30Added POST /shipments — push warehouse-level shipments directly
2026-03-30Added pre-order management: GET/POST /preorder-rules, POST /preorder-rules/{id}/release
2026-03-30Added GET /locations — discover locations across Shopify, Extensiv, Acumatica
2026-03-30Added GET /inventory/locations — per-SKU inventory with location awareness
2026-03-30Added POST /inventory/sync — trigger downstream inventory push
2026-03-30Added POST /orders/simulate — create test orders for integration QA
2026-02-27Added GET /version endpoint; X-WarpWare-API-Version header on all responses
2026-02-27Expanded webhook events: order.created, order.cancelled, order.error
2026-02-27Added POST /orders/bulk — 207 Multi-Status, up to 100 orders per request
2026-02-27Custom API Integration available in dashboard — generate keys without contacting support
2026-02-20Added webhooks: POST/GET/DELETE /webhooks, POST /webhooks/{id}/test
2026-02-20Added GET /orders/stats
2026-02-20Added updated_since filter on orders and inventory
2026-02-20Added idempotency key support on POST /orders
2026-02-15Partner API v1 launched

Ready to integrate?

Contact us to get your API key provisioned and walk through your integration.

Get API Access