TMS Shipment Update

Capture both sides of the margin when your TMS books a carrier. Push AR (what the customer pays you) and AP (what you pay the carrier) — WardenIQ computes actual margin and trains the intelligence engine on real P&L, not just quoted rates.

POST /api/integrations/tms/shipment-update

How the match works

WardenIQ identifies the target lane by lane_ref — a unique identifier WardenIQ assigns to every lane when a quote request is created. The format is REQUESTID-LANENUM-COUNT, for example 1041-030-025. Your TMS should store this lane_ref at the time of quote handoff and include it in every subsequent update.

You can retrieve the lane_ref from the WardenIQ dashboard on the Shipments tab, or (programmatically, in a future release) via a forthcoming outbound feed.

Request body

FieldTypeDescription
lane_refstring (required)The WardenIQ lane identifier. Format: REQUESTID-LANENUM-COUNT. Your TMS stores this at quote-handoff time.
customer_ratenumber (optional)AR — what your customer will actually pay you. Use this to override the original quoted rate when accessorials, detention, or post-booking adjustments change the final number.
truck_costnumber (optional)AP — what you will pay the carrier (booked carrier pay). Stored with source='tms' on the canonical record for audit/rollback.
customer_namestring (optional)Final billable customer name. Use this if your TMS assigns a different customer than what was originally on the quote (e.g. parent company vs subsidiary, or corrected customer record).
carrier_namestring (optional)Carrier name as it appears on the booking confirmation. Displayed on the Shipments tab.
carrier_mcstring (optional)Carrier's Motor Carrier authority number. Stored in carrier_notes.
booked_atISO 8601 string (optional)When the booking was confirmed on your side. Informational; WardenIQ does not currently use this for matching.

Example request

POST /api/integrations/tms/shipment-update HTTP/1.1
Host: wardeniq.com
Authorization: Bearer YOUR_TOKEN_HERE
X-WardenIQ-Timestamp: 1776192000
X-WardenIQ-Signature: sha256=abc123...
Content-Type: application/json

{
  "lane_ref": "1041-030-025",
  "customer_rate": 2650.00,
  "truck_cost": 2250.00,
  "customer_name": "Acme Foods Distribution LLC",
  "carrier_name": "Best Freight Inc",
  "carrier_mc": "MC-123456",
  "booked_at": "2026-04-14T10:00:00Z"
}

Actual margin in this example: $2,650 (customer_rate) − $2,250 (truck_cost) = $400. WardenIQ uses this actual margin to train the intelligence engine — not the rate that was originally quoted.

Example response — success

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "lane_id": 12345,
  "updated": true
}

Example response — lane not found

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "detail": "No lane found for lane_ref=1041-030-025"
}

curl example

#!/bin/bash
SERVICE_TOKEN="eyJ0eXAiOiJKV1Qi..."
SECRET="k3z7Pq2A9fL5wR8vT1mN6yB4hJ0cX..."
BODY='{"lane_ref":"1041-030-025","customer_rate":2650,"truck_cost":2250,"customer_name":"Acme Foods Distribution LLC","carrier_name":"Best Freight Inc","carrier_mc":"MC-123456"}'
TS=$(date +%s)
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://wardeniq.com/api/integrations/tms/shipment-update \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "X-WardenIQ-Timestamp: $TS" \
  -H "X-WardenIQ-Signature: sha256=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

See Authentication for the full explanation of service tokens and HMAC signing.

Side effects

Idempotency

Sending the same payload twice produces the same end state. WardenIQ does not treat a repeated update as an error. If your TMS delivery layer retries on network errors, the duplicate write is safe.

What this endpoint does NOT do