> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wayak.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery exception management

> Automatically detect delays, failed deliveries, and at-risk shipments and alert stakeholders proactively

Delivery exceptions — delays, failed attempts, damaged goods, customs holds — are inevitable in logistics. The problem is not that they happen; it is that they go undetected until a customer calls to complain. By then, the window for mitigation has closed.

Wayak connects your TMS and carrier APIs, scans for exceptions on a schedule, and alerts your operations team and customers before problems escalate. The agent classifies each exception, estimates the impact, and recommends a specific action — escalate, reroute, notify, or hold.

***

## What you need

<CardGroup cols={2}>
  <Card title="Data sources" icon="database">
    * **TMS database** — Shipment records with origin, destination, carrier, service level, planned delivery date, and current status
    * **Carrier tracking APIs** — Real-time tracking events with timestamps, location, status codes, and exception codes
  </Card>

  <Card title="Knowledge spaces" icon="book-open">
    * **SLA documents** — Service-level agreements by carrier and service type with penalty thresholds and escalation procedures
    * **Exception handling procedures** — Internal runbooks for each exception type: who to contact, what to do, and how to communicate to customers
  </Card>
</CardGroup>

**Semantic layer:** Define these in your ontology before setting up the agent.

| Component | Name            | Definition                                                                                                            |
| --------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| Object    | `Shipment`      | Maps to the TMS shipments table. Represents a package or freight movement from origin to destination                  |
| Object    | `Carrier`       | Maps to the carrier master table. Represents a logistics provider with their SLAs and performance history             |
| Metric    | `OnTimeRate`    | Percentage of shipments delivered on or before the planned delivery date                                              |
| Metric    | `ExceptionRate` | Number of shipments with at least one exception divided by total shipments, expressed as a percentage                 |
| Dimension | `ExceptionType` | Categorization: carrier delay, address issue, customs hold, weather disruption, capacity shortage, damaged in transit |

<Tip>
  See [building a semantic layer](/quickstart/build-semantic-layer) for a step-by-step guide.
</Tip>

***

## Agent setup

<Steps>
  <Step title="Create the agent">
    Go to **Agent Space** → **New agent**.

    | Field    | Value                                                                    |
    | -------- | ------------------------------------------------------------------------ |
    | **Name** | Shipment Tracker                                                         |
    | **Role** | Shipment visibility and exception specialist                             |
    | **Goal** | Keep stakeholders informed and catch delays before they impact customers |
  </Step>

  <Step title="Set the description">
    > You track shipments across carriers and flag exceptions. When reporting status, lead with the headline: on-time, delayed, or at-risk. For delays, always include the cause, the revised ETA, and the impact on downstream commitments. Use a factual, calm tone — even when reporting problems. Proactively suggest mitigation options: reroute, expedite, notify customer, or escalate to carrier. Never minimize the severity of a delay.
  </Step>

  <Step title="Scope data access">
    Grant access to:

    * TMS database (shipments, delivery status, carrier assignments)
    * Carrier tracking APIs (real-time tracking events)
    * SLA documents knowledge space
    * Exception handling procedures knowledge space
    * `Shipment`, `Carrier` objects and `OnTimeRate`, `ExceptionRate` metrics
  </Step>

  <Step title="Add skills">
    <AccordionGroup>
      <Accordion title="Generate delivery exception report">
        **Trigger:** Scheduled scan or user request

        1. Pull all active shipments from the TMS with a planned delivery date within the next 48 hours or a status of delayed/failed.
        2. Query carrier tracking APIs for the latest tracking event on each shipment.
        3. Classify each exception by type: carrier delay, address issue, customs hold, weather disruption, capacity shortage, or damaged in transit.
        4. For each exception, calculate: hours past due (or hours at risk), estimated revenue impact, and SLA penalty exposure.
        5. Group exceptions by type and carrier.
        6. Recommend an action for each group: escalate to carrier, notify customer, reroute to alternate carrier, or hold for resolution.
        7. Output a summary table with shipment ID, origin, destination, carrier, original ETA, revised ETA, exception type, and recommended action.
      </Accordion>

      <Accordion title="Track specific shipment">
        **Trigger:** User asks about a specific tracking number or shipment ID

        1. Retrieve the shipment record from the TMS including origin, destination, carrier, service level, and planned delivery date.
        2. Query the carrier tracking API for the full event history.
        3. Determine the current status: in transit (on-time), in transit (at-risk), delayed, delivered, or exception.
        4. If delayed or at-risk, identify the cause from the latest exception code and estimate the revised ETA.
        5. Present the full timeline of tracking events with a status summary and next steps.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

***

## Automation

### Playbook: Daily exception scan

<Steps>
  <Step title="Set the trigger">
    Schedule: **Three times daily at 7:00 AM, 12:00 PM, and 5:00 PM** to catch exceptions during each phase of the delivery day.
  </Step>

  <Step title="Build the workflow">
    1. **Query** the TMS for all in-transit shipments and shipments due for delivery within the next 24 hours.
    2. **Loop** through each shipment:
       * Query the carrier tracking API for the latest event.
       * Compare the current location and timestamp against the expected delivery timeline.
       * If the shipment is behind schedule by more than 2 hours, flag it as at-risk.
       * If the shipment has an exception code, classify it and look up the SLA penalty threshold.
    3. **Condition:** If at-risk shipments exceed 5% of today's deliveries, escalate the report to the logistics director in addition to the standard recipients.
    4. **Aggregate** results into two groups: exceptions requiring immediate action and at-risk shipments to monitor.
  </Step>

  <Step title="Configure delivery">
    Send a Slack message to `#shipment-exceptions` with the exception count and top-priority items. Send an email to the operations team with the full report. For critical exceptions (SLA breach imminent), send a direct Slack message to the account manager for the affected customer.
  </Step>

  <Step title="Test and activate">
    Click **Run now** to test with live data, then toggle to **Active**.
  </Step>
</Steps>

***

## What's next

<CardGroup cols={2}>
  <Card title="Carrier benchmarking" icon="arrow-right" href="/use-cases/logistics/carrier-benchmarking">
    Use exception data to benchmark carrier performance and make smarter allocation decisions.
  </Card>

  <Card title="All logistics use cases" icon="list" href="/use-cases/logistics">
    See the full list.
  </Card>
</CardGroup>