Skip to content

UPS Claims Documentation

Menu Location: Tools > UPS Claims

Access Level: Manager / Administrator

Last Updated: 2026-03-01

Overview

The UPS Claims system allows you to file, manage, and track shipping insurance claims with UPS for lost, damaged, or delayed packages. This streamlined workflow automates claim creation, document uploads, and status tracking, making it easy to recover shipping costs and keep customers satisfied when delivery issues occur.

Primary Functions:

  • Create new shipping insurance claims for orders
  • Submit claims to UPS with required documentation
  • Upload supporting documents (invoices, photos, estimates)
  • Track claim status and updates from UPS
  • Manage claim lifecycle from creation to resolution
  • View API logs and claim history

Page Layout

Header Section

  • New Claim Button: Green button to initiate a new claim
  • Settings Button: Configure UPS API credentials and contact information
  • API Logs Button: View technical logs of UPS API interactions
  • Test/Production Toggle: (Localhost only) Switch between test and live UPS systems

Filter Section

Three filter dropdowns to narrow displayed claims:

  • Order ID: Search for specific order number
  • Week: Filter by weekly cycle
  • Claim Status: Filter by processing status (New, Submitted, etc.)

Claims Table

Displays all claims matching current filters with:

  • Creation date
  • Customer name (linked to account)
  • Order ID
  • Claim status and UPS claim number
  • Notes field for internal tracking
  • Action buttons for each claim

UPS Claims Workflow

Complete 4-Step Process

Step 1: Create New Claim Click "New Claim" and enter order ID or tracking number.

Step 2: Prepare for UPS Fill in claim details including damage description, shipping amount, and loss cause.

Step 3: Submit to UPS Review prepared data and submit to UPS Capital API.

Step 4: Upload Documents Attach required documents like original invoice and photos of damage.

Claim Statuses

Status 0 - New Claim:

  • Claim created but not yet submitted to UPS
  • Requires preparation before submission
  • Shows "Prepare for UPS" button

Status 1 - Submitted to UPS:

  • Claim sent to UPS and awaiting processing
  • Has UPS claim number assigned
  • Shows "Upload Docs" and "Check" buttons

Status 2+ - Various Processing States:

  • UPS is processing the claim
  • Check status updates periodically
  • Monitor for resolution or requests for additional information

Creating a New Claim

Initiate Claim

Purpose: Start the claims process for a problematic shipment

Steps:

  1. Click green "New Claim" button (top right)
  2. Enter Order ID or UPS Tracking Number
  3. Click "Create Claim"
  4. System verifies order exists and creates claim record

Requirements:

  • Valid order ID from your system OR valid UPS tracking number
  • Order must not already have an existing claim
  • Order must have shipping information

What Happens:

  • Claim record created with Status 0 (New)
  • Order linked to claim
  • Customer automatically associated
  • Preparation modal may open automatically

Preparing a Claim for Submission

Fill Claim Details

Purpose: Complete required UPS claim information before submission

Steps:

  1. Click "Prepare for UPS" button on new claim
  2. Select Loss Cause: loss_Ext, damage_Ext, or delay
  3. Review/edit Loss/Damage Description
  4. Verify Shipping Amount (must be greater than $0)
  5. Add internal Notes for your team
  6. Click "Show Advanced Fields" if needed to edit contact info, addresses, etc.
  7. Click "SUBMIT TO UPS" button

Required Fields:

  • Loss Cause: Type of claim (lost, damaged, or delayed)
  • Damage Description: Detailed explanation of the issue
  • Shipping Amount: Claim amount (automatically populated from order)
  • Notes: Internal notes for tracking (not sent to UPS)

Advanced Fields (usually pre-filled from settings):

  • Contact details
  • Sender information
  • Recipient information
  • Payee details
  • Merchandise description
  • Quantities and values

Validation: Shipping amount must be greater than zero, or submission will fail.

Submitting to UPS

Submit Prepared Claim

Purpose: Send claim to UPS Capital for processing

Steps:

  1. Review all claim details in preparation modal
  2. Verify shipping amount is correct
  3. Click "SUBMIT TO UPS" button
  4. Wait for API response (may take 10-30 seconds)
  5. Success: Claim status changes to "Submitted to UPS"
  6. Failure: Error message displays, correct issues and retry

On Success:

  • UPS Claim Number assigned
  • Status updates to 1 (Submitted)
  • Document upload modal opens automatically
  • Original invoice begins uploading

On Failure:

  • Error message explains the problem
  • Claim remains in Status 0
  • Fix highlighted issues and resubmit
  • Common errors: missing required fields, invalid amounts

Uploading Documents

Manage Claim Documentation

Purpose: Provide UPS with required evidence for claim processing

Steps:

  1. Click "Upload Docs" button on submitted claim
  2. Original Invoice: Click "Send Now" to auto-generate and upload
  3. Additional Documents: Click "Upload New Doc" for photos, estimates, etc.
  4. Select document type from dropdown
  5. Choose file (PDF, JPG, PNG, DOC, XLS, TXT allowed)
  6. Click "Upload File to UPS"
  7. Verify successful upload confirmation

Document Types

1. Original Invoice (UPS_CLAIM_UP_INVOICE_EXT):

  • Automatically generated from order data
  • Shows items, prices, and shipping cost
  • One-click upload after claim submission

2. Photo - External (UPS_CLAIM_UP_PHOTO_EXT):

  • Photos of damaged packaging exterior
  • Shows shipping label and damage

3. Photo - Repair Estimate (UPS_CLAIM_UP_PHOTO_REPAIRESTIMATE):

  • Quotes or estimates for repairs
  • Vendor assessments of damage

4. Photo - Other (UPS_CLAIM_UP_PHOTO_OTHER):

  • Any other supporting documentation
  • Contents photos, correspondence, etc.

Allowed File Types

  • Images: JPEG, PNG
  • Documents: PDF, DOC, XLS, TXT
  • Max file size: System handles compression automatically
  • Recommendation: Keep files under 5MB for best performance

Deleting Uploads

  • Click trash icon next to uploaded document
  • Confirm deletion
  • Document removed from UPS and local records
  • Can re-upload if needed

Checking Claim Status

Monitor Claim Progress

Purpose: Get updates from UPS on claim processing status

Steps:

  1. Locate claim in table (Status 1 or higher)
  2. Click "Check" button (with refresh icon)
  3. Wait for API call to complete
  4. Success message shows current status
  5. Status displays below UPS claim number

Status Examples:

  • "Submitted"
  • "Under Review"
  • "Approved"
  • "Denied"
  • "Additional Information Required"

Frequency:

  • System does not auto-check
  • Manually check weekly or as needed
  • More frequent checking won't speed UPS processing

Last Checked Timestamp: Small gray text below claim status shows when it was last checked.

Viewing Claim Logs

Access Claim History

Purpose: Review complete history of a claim including all status checks and uploads

Steps:

  1. Click "Logs" button for any claim
  2. Review three tabs:
    • Claim Check History: Status checks and timestamps
    • Shipping Log: Package tracking events from EasyPost
    • API Data: Raw claim submission data

Claim Check History Tab:

  • Every status check recorded
  • Timestamp of each check
  • Status returned by UPS

Shipping Log Tab:

  • Original shipment tracking events
  • Delivery attempts and failures
  • Estimated delivery dates
  • Useful for understanding why claim was needed

API Data Tab:

  • Raw JSON data submitted to UPS
  • Technical details of claim
  • Useful for troubleshooting with support

Editing Claim Notes

Update Internal Notes

Purpose: Add tracking information visible only to your team

Steps:

  1. Hover over Notes column for any claim
  2. Click the edit icon (wrench) that appears
  3. Type or edit notes in text area
  4. Click "Save Note" button
  5. Notes update in table instantly

Use Notes For:

  • Customer communication history
  • Internal status updates
  • Special instructions
  • Related order numbers or issues
  • Follow-up reminders

Deleting Claims

Remove Claim Record

Purpose: Delete claim that was created in error or is no longer needed

Steps:

  1. Click trash icon on far right of claim row
  2. Confirm deletion in popup
  3. Claim removed from system
  4. Customer log entry created recording deletion

Warning: Deletion is permanent and cannot be undone. Only delete claims that were created in error or are definitively unnecessary.

Not Recommended For:

  • Denied claims (keep for records)
  • Completed claims (keep for accounting)
  • Claims pending UPS response

Settings Configuration

UPS API Credentials

Purpose: Configure connection to UPS Capital claims system

Settings Fields:

  • Partner ID: Your UPS Capital partner identification
  • Policy Number: Your shipping insurance policy number
  • X-IBM-Client-Id: API client identifier
  • X-IBM-Client-Secret: API client secret key
  • Bearer Token: Authentication bearer token
  • API Endpoints: URLs for claim creation, document upload, status checking

Contact Information:

  • First Name, Last Name
  • Phone Number
  • Email Address
  • Street Address, City, State, Postal Code

When to Update:

  • Initial system setup
  • If UPS changes API credentials
  • When changing insurance policies
  • If contact information changes

Important: Incorrect settings will cause all claim submissions to fail. Contact Kiva Logic support if you need to update API credentials.

Common Use Cases

Use Case 1: File Claim for Lost Package

Goal: Get reimbursement for package that never arrived at customer

Steps:

  1. Verify package is truly lost (check tracking, wait appropriate time)
  2. Click "New Claim", enter Order ID
  3. Click "Prepare for UPS"
  4. Select "loss_Ext" as Loss Cause
  5. Enter description: "Package never delivered, tracking shows lost in transit"
  6. Verify shipping amount
  7. Click "SUBMIT TO UPS"
  8. Upload original invoice when prompted
  9. Upload any carrier correspondence if available
  10. Check status weekly until resolved

Example: Order #12345 shipped 10 days ago, tracking shows "lost in transit." File claim, submit with auto-generated invoice, approved within 2 weeks.

Use Case 2: Handle Damaged Delivery

Goal: Get reimbursement when customer receives damaged products

Steps:

  1. Ask customer to photograph damaged packaging and contents
  2. Create new claim with order ID
  3. Prepare claim selecting "damage_Ext"
  4. Describe damage: "Box crushed, glass bottles broken, contents spoiled"
  5. Submit to UPS
  6. Upload original invoice
  7. Upload customer's photos as "Photo - External"
  8. If repair possible, upload estimate as "Photo - Repair Estimate"
  9. Check status and respond to any UPS requests

Tips:

  • Get detailed photos from customer before they discard packaging
  • More documentation = faster approval
  • Include photos showing shipping label on damaged box

Use Case 3: Claim for Delayed Delivery

Goal: Recover costs when late delivery causes spoilage

Steps:

  1. Verify delivery was genuinely late (perishable goods spoiled)
  2. Create claim for the order
  3. Select "delay" as Loss Cause
  4. Explain: "Delivery 3 days late, perishable produce spoiled"
  5. Include original expected delivery date in description
  6. Submit claim
  7. Upload invoice showing perishable items
  8. Upload photo evidence of spoilage if customer provided

Note: Delay claims may be harder to get approved. Strong documentation of perishability and spoilage is essential.

Use Case 4: Bulk Process Multiple Claims

Goal: Efficiently file claims for several problematic shipments

Steps:

  1. Compile list of order IDs needing claims
  2. Create all claims first (New Claim > enter ID > repeat)
  3. Filter to Status 0 to see only new claims
  4. Prepare each claim one by one
  5. Submit all prepared claims
  6. Return to upload invoices in bulk
  7. Note any that need additional photos
  8. Follow up for photo uploads from customers

Tips:

  • Work in batches to minimize context switching
  • Keep spreadsheet of claims and their statuses
  • Set reminders to check all claims weekly

Use Case 5: Follow Up on Pending Claim

Goal: Keep claim moving through UPS system and respond to requests

Steps:

  1. Filter to Status 1 (Submitted) claims
  2. Click "Check" on claims older than 1 week
  3. Review status updates
  4. If "Additional Information Required", click "Logs"
  5. Check what UPS is requesting
  6. Upload requested documents via "Upload Docs"
  7. Make note in Notes field of what was provided
  8. Check again in 3-5 business days

Example: Claim shows "Need photo of damage." Upload customer's photos via "Upload New Doc" > Photo - External, then check status again in a week.

Report Data & Columns

Column Description Actions
Created Date claim was created in system Hover for full timestamp
Customer Customer name linked to claim Click to view customer account
Order ID Order number associated with claim Links to order details
Status Current processing status Shows UPS claim number if submitted
Notes Internal notes and tracking info Click edit icon to modify
(Actions) Available actions for claim Logs, Prepare, Upload, Check, Delete

Filters & Search Options

Filter Controls

  • Order ID: Enter specific order number to find its claim
  • Week: Select weekly cycle to see claims from that delivery period
  • Claim Status: Choose 0 (New), 1 (Submitted), or All

Applying Filters

  1. Select desired filter values
  2. Click "Load" button
  3. Table refreshes with matching claims
  4. Clear filters to see all claims

Troubleshooting

Claim Submission Fails with "Shipping Amount Must Be Greater Than Zero"

Symptoms: Error message when clicking SUBMIT TO UPS

Solutions:

  1. Click "Prepare for UPS" again
  2. Find "Shipping Amount" field (may need to show advanced fields)
  3. Enter the claim amount (should match order shipping cost)
  4. Ensure value is numeric and > 0
  5. Click SUBMIT TO UPS again

Common Causes:

  • Shipping amount not captured from original order
  • Field accidentally cleared
  • Order had free shipping (but still has shipping insurance value)

Original Invoice Upload Fails

Symptoms: Upload spinner runs but shows error or never completes

Check:

  1. Verify order exists and has line items
  2. Confirm claim has been submitted to UPS (Status 1)
  3. Try refreshing page and clicking "Upload Docs" again
  4. Check if invoice was already uploaded successfully

If Problem Persists: Contact Kiva Logic support—may be PDF generation issue.

Can't Find Claim for Specific Order

Symptoms: Order had shipping issue but no claim appears

Solutions:

  1. Clear all filters and search through entire list
  2. Check if claim was created under different order ID
  3. Verify order ID is correct
  4. Create new claim if none exists

Prevent: Use Order ID filter immediately after creating claim to verify it worked.

UPS Check Returns Error

Symptoms: Clicking "Check" button shows API error message

Check:

  1. Verify UPS API credentials in Settings are correct
  2. Confirm UPS claim number exists for this claim
  3. Check API Logs page for specific error details
  4. Wait a few hours and try again (UPS API may be temporarily down)

If Problem Persists: This is usually a UPS API issue or credentials problem. Contact Kiva Logic support.

Uploaded Document Not Showing

Symptoms: File uploaded but doesn't appear in document list

Solutions:

  1. Refresh the "Upload Docs" modal
  2. Check file size (very large files may fail silently)
  3. Verify file type is allowed (PDF, JPG, PNG, DOC, XLS, TXT)
  4. Try a smaller file or different format
  5. Re-upload the document
  • UPS Claims API Logs (ups-claims-api-calls.php) - Technical logs of all UPS API interactions
  • Orders (orders.php) - View order details to understand claim context
  • Customer Info (customer_info.php) - Customer account linked to claim
  • EasyPost Settings (easypost-settings.php) - Shipping configuration that generates tracking data

Typical Workflow:

  1. Orders page → Notice shipping issue → UPS Claims → Create claim
  2. UPS Claims → Prepare → Submit → Upload Docs → Check status
  3. UPS Claims → View Logs → Shipping Log → Understand delivery problem

Permissions & Access

Required Access Level: Manager or higher

Access Level Capabilities:

  • Customer Service: Cannot access UPS Claims
  • Manager: Create, submit, and track claims; upload documents; view logs
  • Administrator: All Manager capabilities plus edit settings
  • Kiva Admin: All features plus test/production toggle and API configuration

Restricted Features:

  • Settings: Requires Administrator or Kiva Admin
  • Test/Production Toggle: Kiva Admin only (localhost only)

Best Practices

When to File Claims

  1. File promptly—don't wait more than 30 days after shipping
  2. Verify issue before filing (check tracking thoroughly)
  3. Collect evidence from customer immediately (photos degrade over time)
  4. File even for small amounts—insurance is there to use

Documentation Standards

  1. Always upload original invoice (required)
  2. Get detailed photos of damage: box exterior, label, contents
  3. Include shipping label clearly visible in at least one photo
  4. Save all carrier correspondence
  5. Document customer complaints and reports

Status Management

  • Check new claims weekly
  • Update notes field with every significant action
  • Respond to UPS requests within 24-48 hours
  • Keep customers informed of claim progress
  • Don't close customer service tickets until claim resolved

Things to Avoid

  • ❌ Deleting claims that were denied (keep for records)
  • ❌ Filing claims without proper documentation
  • ❌ Waiting too long to file (insurance has time limits)
  • ❌ Forgetting to upload original invoice (required for processing)
  • ❌ Ignoring "Additional Information Required" status updates

Quick Reference Card

Task Action/Location
Create new claim Click "New Claim" button, enter order ID
Prepare claim Click "Prepare for UPS" on new claim
Submit to UPS Fill claim details, click "SUBMIT TO UPS"
Upload invoice Click "Upload Docs", click "Send Now"
Upload photos Click "Upload Docs", "Upload New Doc", select file
Check status Click "Check" button with refresh icon
View claim history Click "Logs" button
Edit notes Hover over notes, click edit icon
Delete claim Click trash icon, confirm deletion
Configure API Click "Settings" button at top
View API logs Click "API Logs" button at top
Filter claims Select filters, click "Load"

FAQs

How long does UPS take to process claims?

Typically 7-14 business days for straightforward claims. Complex claims may take 3-4 weeks. Incomplete documentation delays processing significantly.

Do I need to provide original packaging?

UPS may request the original packaging be held for inspection, especially for high-value claims. Keep packaging until claim is approved or UPS explicitly says it's not needed.

Can I file a claim for a package marked "delivered" but customer didn't receive?

Yes, file a "loss_Ext" claim. Include any porch pirate reports, police reports, or carrier investigation results. Document customer's statement that they never received it.

What's the maximum claim amount?

Depends on your insurance coverage. Most packages are insured for their declared value. Very high-value shipments may need additional documentation. Check your UPS Capital policy.

Can I edit a claim after submitting to UPS?

No, you cannot edit claim details after submission. If critical information was wrong, delete and recreate the claim. For minor issues, add notes in the Notes field and respond to any UPS requests for clarification.

What happens if my claim is denied?

Review the denial reason in the status. Common reasons: insufficient documentation, not filed timely, damage not shipping-related. You may be able to appeal with additional evidence. Contact UPS Capital directly for appeals.

Should I refund/replace customer order before claim is approved?

This is a business decision. Many businesses replace the order immediately for customer satisfaction, then recover costs through the claim. Others wait for claim approval. Consider: customer relationship value, claim amount, likelihood of approval.

Can I track multiple claims for the same order?

The system prevents creating duplicate claims for the same order ID. If you need to file multiple claims (e.g., partial delivery), contact Kiva Logic support for guidance.

Change Log

2026-03-01

  • Initial documentation created
  • Complete workflow documentation from creation through resolution
  • All sections completed with detailed use cases

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.