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

# ShipTheory audit profile, Vortex IQ

> What the Vortex IQ ShipTheory health audit checks: ShipTheory: Label Generation, Sub-Carrier Mix Health & Cross-Channel Leak

**[Nerve Centre KPIs](/nerve-centre/kpi-cards/ship-theory) · [Audit Profile](/nerve-centre/kpi-cards/ship-theory/audit) · [Sentiment Settings](/nerve-centre/kpi-cards/ship-theory/sentiment)**

ShipTheory is a UK shipping aggregator - a single integration that fans out to Royal Mail, DPD, Hermes, Parcelforce, etc. underneath. CloudHub probe shows 4 active merchants on bearer-token auth (BaseUrl api.shiptheory.com/v1, 2023-07 last refresh). Findings either lose money (label-generation failures = orders can't despatch) or hide carrier mistakes behind the aggregator. Cross-references commerce siblings via order\_ref; sub-carrier shipments via parent\_consignment.

## What this audit checks

### Authentication & access

* Bearer token still valid (no 401 on /account)
* Token re-issuance via /token (login\_email + password) succeeds when expired
* Token expiry tracked - re-auth triggered before expiry rather than on 401
* Sandbox vs production base URL flagged correctly

### Label generation (the ShipTheory core SLA)

* Label-generation success \< 98% rolling 24h
* Address-validation failure rate > 2%
* Service-eligibility miss > 1% (label requested for unsupported route)
* Manifest gap (LabelPrinted >24h with no OnManifest event) > 0.5%

### Sub-carrier consolidation health

* Single-sub-carrier dependency > 80% (defeats consolidation point)
* Sub-carrier OTD spread > 10pp (one sub-carrier dragging aggregate down)
* New sub-carrier added without OTD baseline established
* Sub-carrier route-cost drift > 10% WoW

### Exceptions, claims & failed pickups

* Exception rate > 3% rolling 30D
* Open claims unresolved > 7 days
* Failed-pickup rate > 3% (cross-sub-carrier)
* Refused-parcel rate > 1%

### Cost & service-mix economics

* Avg cost / shipment up >10% vs prior period
* Sub-carrier rate-card drift > 10% on any single carrier WoW
* Premium-service uplift > 30% WoW (sub-carrier mix shifting expensive)
* Claim value as % of ShipTheory revenue > 2% rolling 90D

### Cross-channel: revenue at risk (the kill-shot area)

* Cross-channel: late shipments joined to commerce\_sibling orders -> revenue at risk per channel
* Cross-channel: label-gen failures correlated with order\_ref - which channels have malformed addresses
* Cross-channel: open claims with no Jira tracker\_item -> CS coverage gap
* Cross-channel: sub-carrier blame attribution (when ShipTheory routes via DPD/Royal Mail underneath, which carrier owns the late delivery)

## Severity thresholds

| Signal                               | Warn | Critical |
| ------------------------------------ | ---- | -------- |
| `on_time_delivery_rate`              | 95   | 90       |
| `label_generation_success_pct`       | 99   | 98       |
| `address_validation_fail_pct`        | 1    | 2        |
| `manifest_gap_pct`                   | 0.3  | 0.5      |
| `exception_rate`                     | 2    | 3        |
| `open_claims_age_days`               | 7    | 14       |
| `failed_pickup_rate_pct`             | 2    | 3        |
| `shipping_cost_per_order_change_pct` | 5    | 10       |
| `sub_carrier_concentration_pct`      | 70   | 80       |
| `sub_carrier_otd_spread_pp`          | 7    | 10       |
| `claim_value_pct_of_revenue`         | 1    | 2        |
| `auth_token_failures_24h`            | 1    | 5        |

## Data sources

* `POST https://api.shiptheory.com/v1/token` - Bearer token issuance / refresh
* `GET https://api.shiptheory.com/v1/account` - Auth probe + account metadata
* `GET https://api.shiptheory.com/v1/shipments` - Shipment list + label-gen success
* `GET https://api.shiptheory.com/v1/tracking/{shipment_id}` - Tracking events (cross-sub-carrier)