Available · v1

Shipment Intelligence

Send a shipment's tracking events, promised date, and any customer message. Get back the exception type, priority, and the workflow that should handle it.

  • Carrier messages interpreted in time order
  • Lateness computed exactly from your dates
  • Suspected and carrier-confirmed losses kept apart
  • Never issues refunds, replacements, or claims
Try it in the playgroundAPI referenceGuides
Request body
{
  "shipment_id": "SHP-48213",
  "carrier": "Example Parcel",
  "events": [
    {
      "timestamp": "2026-03-02T09:10:00Z",
      "status": "PU",
      "description": "Picked up",
      "location": "Columbus, OH"
    },
    {
      "timestamp": "2026-03-03T22:41:00Z",
      "status": "IT",
      "description": "Departed sort facility",
      "location": "Indianapolis, IN"
    },
    {
      "timestamp": "2026-03-05T14:05:00Z",
      "status": "EX",
      "description": "Delivery exception: weather delay at destination facility",
      "location": "Denver, CO"
    }
  ],
  "promised_delivery_date": "2026-03-05",
  "as_of": "2026-03-08T12:00:00Z",
  "service_policy": {
    "no_scan_days": 2,
    "escalate_days_late": 3
  }
}
Response · 200 OK
{
  "request_id": "req_Tz7nW2qLr5YbK9cM",
  "exception_type": "delayed",
  "priority": "high",
  "recommended_action": "contact_carrier",
  "requires_human_review": false,
  "signals": [
    "past_promised_date",
    "no_recent_scan"
  ],
  "missing_information": [],
  "days_past_promised": 3,
  "days_since_last_event": 2
}
The problem

Tracking exceptions are written for people, not workflows

Every carrier phrases delays, failed attempts, address problems, and damage differently. Support and logistics teams read each one to decide who should act.

Exception classification
Delayed, failed delivery, address issue, damaged, lost, delivery dispute, customs hold, or no exception.
Deterministic timing
Days past the promised date and days since the last scan come from your timestamps, with your escalation thresholds.
Workflow routing
Monitor, contact the carrier, contact the customer, investigate, or send to a person when it's unclear.
Use cases

Where teams use it

  • Delivery exception handling
  • Logistics support
  • Customer delivery inquiries
  • Post-purchase experience
  • 3PL operations
Integrate

One HTTP call

const response = await fetch("https://kovca.io/api/v1/shipments/triage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOVCA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "shipment_id": "SHP-48213",
    "carrier": "Example Parcel",
    "events": [
      {
        "timestamp": "2026-03-02T09:10:00Z",
        "status": "PU",
        "description": "Picked up",
        "location": "Columbus, OH"
      },
      {
        "timestamp": "2026-03-03T22:41:00Z",
        "status": "IT",
        "description": "Departed sort facility",
        "location": "Indianapolis, IN"
      },
      {
        "timestamp": "2026-03-05T14:05:00Z",
        "status": "EX",
        "description": "Delivery exception: weather delay at destination facility",
        "location": "Denver, CO"
      }
    ],
    "promised_delivery_date": "2026-03-05",
    "as_of": "2026-03-08T12:00:00Z",
    "service_policy": {
      "no_scan_days": 2,
      "escalate_days_late": 3
    }
  }),
});

if (!response.ok) {
  const { error, request_id } = await response.json();
  throw new Error(`${error.code}: ${error.message} (${request_id})`);
}

const { exception_type, priority, recommended_action } = await response.json();

Related APIs

  • Support Triage

    Classify inbound support tickets by category and priority, and flag the ones a person should review.

  • Incident Intelligence

    Classify incidents, evaluate severity against your escalation policy, and recommend handling.

  • Lead Intelligence

    Qualify inbound leads by stated intent and your criteria, and recommend follow-up priority.