Ship Claims Operations

---
title: SHIP Claims Operations Runbook
description: End-to-end SHIP claims operations guide for intake, evidence requirements, escalation paths, and operator actions.
owner: ops
last_reviewed: 2026-03-03
audience: internal
status: active
---
 
# SHIP Claims Operations Runbook
 
Purpose: define the operating routine for SHIP claims from intake through resolution, including evidence requirements, escalation, and support triage.
 
Audience: customer operators, internal ops, and docs-fed assistant workflows.
 
---
 
## Intake Cadence
 
Daily (business days):
- Review new findings in `/ship/audit`.
- Triage all `OPEN` findings generated since previous run.
- Advance clear candidates to `DISPUTED` with an owner and due date.
 
Weekly:
- Run dispute aging review for `DISPUTED`, `SUBMITTED`, `CARRIER_REVIEW`.
- Escalate findings within 7 days of dispute deadline.
- Export status report for customer operations lead.
 
Monthly:
- Reconcile `CREDITED` findings against carrier documentation.
- Confirm billing gate inputs in `ship-billing-controls.md` before invoice generation.
 
---
 
## Workflow States and Operator Actions
 
### `OPEN`
- Meaning: finding detected; no operator action taken.
- Operator action:
  - Validate evidence quality and expected amount context.
  - Choose `DISPUTED` when claim-worthy.
  - Choose `DISMISSED` if non-actionable.
 
### `DISPUTED`
- Meaning: operator marked finding for claim submission.
- Operator action:
  - Attach dispute rationale and carrier-facing summary.
  - Move to `SUBMITTED` once packet is sent.
  - Use `CREDITED` only with confirmed credit evidence.
  - Use `REJECTED` only with explicit carrier denial evidence.
 
### `SUBMITTED`
- Meaning: claim submitted to carrier; awaiting acknowledgement.
- Operator action:
  - Record submission reference and channel (required).
  - Move to `CARRIER_REVIEW` when carrier confirms in-review.
  - Move to `CREDITED` only after credit memo/refund confirmation.
  - Move to `REJECTED` only after documented denial.
 
### `CARRIER_REVIEW`
- Meaning: carrier accepted claim for review; pending outcome.
- Operator action:
  - Track SLA and chase stale reviews.
  - Move to `CREDITED` only with confirmation payload.
  - Move to `REJECTED` on formal denial.
 
### `CREDITED`
- Meaning: confirmed carrier credit/refund received.
- Operator action:
  - Ensure credit evidence and confirmation reference are captured.
  - Close internal follow-up tasks.
 
### `REJECTED`
- Meaning: carrier denied claim.
- Operator action:
  - Capture denial reason and source artifact.
  - Decide reopen vs close.
 
### `DISMISSED`
- Meaning: finding intentionally not pursued.
- Operator action:
  - Record reason for no-action decision.
 
### `REOPEN`
- Use only when prior state was wrong or new evidence is available.
 
---
 
## Evidence Requirements by Transition
 
`OPEN -> DISPUTED`
- Required:
  - Operator rationale
  - Initial supporting evidence (invoice/screen output)
 
`DISPUTED -> SUBMITTED`
- Required:
  - Submission timestamp
  - Submission channel (portal/email/API)
  - Carrier claim/ticket reference (`externalReference`)
 
`SUBMITTED -> CARRIER_REVIEW`
- Required:
  - Carrier acknowledgement artifact
  - Acknowledgement date
  - Carrier acknowledgement reference (`externalReference`)
 
`DISPUTED|SUBMITTED|CARRIER_REVIEW -> CREDITED`
- Required:
  - Confirmed amount (>0)
  - `confirmation.source`
  - `confirmation.referenceId`
  - `confirmation.confirmedAt` (ISO timestamp)
- Optional:
  - Notes
  - Artifact URL
 
`DISPUTED|SUBMITTED|CARRIER_REVIEW -> REJECTED`
- Required:
  - Carrier denial source
  - Denial reason (if provided)
  - Denial timestamp
 
---
 
## External Reference Examples
 
Use `externalReference` values that are traceable in carrier systems and stable across follow-up.
 
Accepted examples:
- Carrier portal claim ID: `CLM-2026-004182`
- Carrier case/ticket ID: `CASE-8842191`
- Email-thread subject reference when no portal ID exists: `UPS-CLAIM-1Z999AA10123456784-2026-03-01`
 
Guidelines:
- Use one canonical value per transition action.
- Do not use internal-only notes like "submitted by ops".
- If a new carrier reference supersedes an old one, record the new value and include the old value in notes/artifact context.
 
---
 
## Escalation Matrix
 
Level 1 (Operator):
- Owns daily triage and standard transitions.
 
Level 2 (Customer Ops Lead):
- Trigger:
  - Any claim `<= 7` days from deadline with no `SUBMITTED` state.
  - Any stale `CARRIER_REVIEW` > 10 business days.
- Action:
  - Reprioritize queue, contact carrier escalation path.
 
Level 3 (Internal Platform/Ops):
- Trigger:
  - Workflow/API errors blocking claim progression.
  - Data anomalies causing repeated false positives.
- Action:
  - Incident triage, route to platform on-call, attach run logs and finding IDs.
 
Level 4 (Executive/Account):
- Trigger:
  - High-value dispute risk or recurring SLA misses.
- Action:
  - Coordinate customer-level decision and remediation plan.
 
---
 
## Failure Handling Playbooks
 
### API or UI action fails
- Capture:
  - timestamp
  - endpoint/action
  - finding IDs
  - error body
- Retry once.
- If still failing, escalate to Level 3.
 
### Duplicate or conflicting credits
- Do not retry with a new reference ID.
- Validate existing credit event by `referenceId`.
- If mismatch exists, escalate to Level 3 before billing cut.
 
### Missing evidence artifact
- Hold transition in current state.
- Create operator task with owner/date.
- Escalate to Level 2 if deadline risk exists.
 
### Dispute deadline breach risk
- Bulk review all `OPEN` and `DISPUTED` findings with near deadlines.
- Prioritize submission first, enrichment second.
 
---
 
## What Support Asks First (Checklist)
 
- Tenant/org name and environment.
- Finding ID(s) and current workflow state.
- What action failed or what outcome is expected.
- Submission reference (`externalReference`).
- Credit reference ID (if issue is credit/billing related).
- Screenshot or raw API error payload.
- Business deadline impact (date and value at risk).
 
---
 
## Operating Notes for Docs-Fed Assistant
 
- Prefer procedural answers mapped to workflow states.
- Never instruct crediting without confirmation evidence fields.
- Route billing policy questions to `ship-billing-controls.md`.
- Escalate to human operator when required evidence is missing.