Skip to content

Shipping Report Documentation

Menu Location: Reports > Shipping > Shipping Report

Access Level: Manager / Administrator

Last Updated: 2026-03-01

Overview

The Shipping Report tracks package delivery performance through integration with EasyPost shipping APIs. It identifies late or missing shipments, allows you to create claims or reship orders, and monitors carrier performance against delivery estimates.

Primary Functions:

  • Track shipment delivery status and timing
  • Identify late or missing packages
  • Create resolution actions (reship, credit, refund, claim, ignore)
  • Monitor actual vs estimated shipping times
  • Generate reports for carrier performance analysis
  • Export shipping data to CSV

Page Layout

Header Section

  • Page Title: Shipping Report
  • Update Arrival Date Button: Refreshes tracking data via API
  • Sort Order Configuration: Drag-and-drop tiles to customize table sorting

Filter Controls

  • Order or Tracking ID Search: Find specific shipment
  • Week Selector: Choose weekly_cycle for analysis
  • Delivery Time Filter: On Time / All / Late / Missing Data
  • Build Shipping Report Button: Generates report with current settings

Main Content Area

  • Report Table: Shows orders with shipping details and statuses
  • Totals Summary: Breakdown by shipping days, status, origin scan dates
  • Action Modals: Pop-up forms for handling problem shipments
  • Deal With It System: Track resolution of shipping exceptions

Report Data & Columns

Column Description Calculation/Source
Order ID Customer order number Links to order details, includes API refresh icon
Name Customer name and tracking number Last name, first name plus tracking code and last checked timestamp
Last Status Most recent tracking status From easypost_tracking_data table
Est. Shipping Estimated delivery days From EasyPost shipment data (ep_ship_days)
Shipped On Origin scan date/time From origin_scan field, may show "5am adjustment"
Arrived On Delivery confirmation date/time From arrival_date field
Shipping Days Actual days in transit DATEDIFF between origin scan and arrival
(Action Column) Resolution status badge Shows credit, reship, refund, claim, or ignore status
(Deal With It) Action button or status Button to resolve issue or status badge if already handled

Delivery Time Filters

On Time (2 days or less)

What It Shows:

  • Shipments delivered within 2 days
  • arrival_date field populated
  • Calculated shipping days ≤ 2

When to Use:

  • Verify carrier performance
  • Confirm majority of shipments on time
  • Identify baseline performance

All

What It Shows:

  • Every shipment regardless of status
  • Includes on-time, late, in-transit, and missing data
  • No filtering by delivery speed

When to Use:

  • Complete shipment overview
  • Export full dataset
  • General monitoring

Late (3 days or more)

What It Shows:

  • Shipments taking 3+ days to deliver
  • arrival_date populated AND shipping_days ≥ 3
  • OR origin_scan exists but arrival_date = 0 and 3+ days have passed

When to Use:

  • Identify problem shipments
  • Create claims or offer compensation
  • Monitor carrier issues
  • Focus on customer satisfaction risks

Missing Origin and/or Delivered Data

What It Shows:

  • Orders where origin_scan = 0 OR arrival_date = 0
  • Incomplete tracking information
  • May indicate tracking not yet available or shipment issues

When to Use:

  • Find shipments needing API refresh
  • Identify tracking data gaps
  • Investigate possible shipping errors

Deal With It Action System

Available Actions

Reship:

  • Creates new replacement order
  • Select delivery week for reship
  • Original order remains in system
  • Logs action to customer account
  • Option to send email notification

Credit:

  • Applies account credit for order amount
  • Uses actual_total from order
  • Creates cust_order_payment credit entry
  • Logs to customer account
  • Option to send email notification

Refund:

  • Marks order as refunded
  • Tracks refund status
  • Logs to customer account
  • Option to send email notification

Ignore:

  • Marks shipment exception as reviewed
  • No customer action taken
  • Logs to customer account
  • Useful for borderline cases

Claim:

  • Creates UPS/carrier claim record
  • Links to ups_claims table
  • Tracks claim status and resolution
  • Assigns claim number

Deal With It Workflow

Step 1: Identify Issue

  • Report shows late or missing shipment
  • "Deal With It" button appears for eligible orders

Step 2: Open Action Modal

  • Click "Deal With It" button
  • Modal shows order details and action options
  • Note field for documentation

Step 3: Add Notes

  • Enter explanation or customer communication details
  • Notes saved to shipping_report_notes table
  • Automatically added to customer account

Step 4: Select Action

  • Choose resolution (reship, credit, refund, ignore)
  • Configure action specifics (e.g., reship week)
  • Confirm action

Step 5: Send Email (Optional)

  • Review auto-populated email template
  • Edit subject and body if needed
  • Click "Send Email" to queue message
  • Email links to customer account

Step 6: Completion

  • Action badge replaces "Deal With It" button
  • dealwithit_action and dealwithit_data updated in order record
  • Status visible in table for future reference

Undoing/Changing Actions

How It Works:

  • Clicking an action badge reopens modal
  • Selecting new action reverses previous action
  • Credit reversed: Creates offsetting debit
  • Reship reversed: Cancels replacement order
  • New action applied after reversal

Warning:

  • Only one action can be active at a time
  • Changing actions creates audit trail in logs
  • Email notifications aren't automatically reversed

Filters & Search Options

What to Enter:

  • Customer order ID number
  • EasyPost tracking code
  • Searches both fields with OR logic

Behavior:

  • Overrides week filter when used
  • Shows "Missing data" filter automatically
  • Displays single order results
  • Includes rocket icon to refresh just this order's tracking

Week Selector

Default: Current week (getWeekId()) Shows: All orders scheduled for selected week Filters: weekly_cycle_id field

Delivery Time Selector

Purpose: Focus on specific delivery performance categories Default: "On Time - 2 days or less" Options: See Delivery Time Filters section above

Sort Order Customization

Feature: Drag-and-drop sort priority

Available Sort Options:

  • Status (last_status)
  • Est. Shipping Time (ep_ship_days)
  • Shipping Date (origin_scan)
  • Arrival Date (arrival_date)
  • Shipping Days (calculated shipping_days)
  • Customer Name (last_name, first_name)

How to Use:

  1. Drag tiles to reorder priority
  2. Order automatically saved to config
  3. Report table sorts based on tile order (left to right = primary to tertiary)
  4. Persists across sessions

Default Order:

  1. Status
  2. Est. Shipping Time
  3. Shipping Date
  4. Arrival Date
  5. Shipping Days
  6. Customer Name

Common Use Cases

Use Case 1: Weekly Late Shipment Review

Goal: Identify and resolve all late shipments from previous week

Steps:

  1. Select previous week from dropdown
  2. Select "Late - 3 days or more" filter
  3. Click "Build Shipping Report"
  4. Review each late shipment
  5. For each: Click "Deal With It"
  6. Add notes explaining situation
  7. Choose action (typically credit or reship)
  8. Send customer notification email
  9. Export results to CSV for records

Example: Week of March 1-7 shows 8 late shipments. 5 receive credits, 2 get reships, 1 ignored (customer contacted directly).

Tips:

  • Handle within 48 hours of delivery date
  • Prioritize customers with repeated issues
  • Track patterns by carrier or destination

Use Case 2: Monitor Carrier Performance

Goal: Track delivery performance against carrier promises

Steps:

  1. Select date range (use week selector multiple times)
  2. Run report with "All" filter
  3. Export to CSV
  4. Review "Totals" section at bottom
  5. Note percentages for on-time vs late
  6. Compare Est. Shipping vs Actual Shipping Days
  7. Document for carrier negotiations

Example: Carrier promised 95% on-time (2 days). Report shows only 78% meeting target. Use data for service credit request.

Tips:

  • Run monthly for trend analysis
  • Compare carriers if using multiple
  • Use data in contract negotiations
  • Track improvement after carrier changes

Use Case 3: Missing Tracking Data Investigation

Goal: Find and resolve orders without complete tracking info

Steps:

  1. Select current week
  2. Select "Missing Origin and/or Delivered data"
  3. Click "Build Shipping Report"
  4. For each order, click rocket icon to refresh API data
  5. Wait for API update (check "Last Checked" timestamp)
  6. Reload report to see if data now available
  7. For persistent missing data, contact carrier

Example: 10 orders show missing origin scan. API refresh updates 8, leaving 2 to investigate with carrier.

Tips:

  • Try API refresh 2-3 times before escalating
  • Some carriers delay tracking updates
  • Missing data after 48 hours needs investigation
  • Update Arrival Date button can batch process

Use Case 4: Customer Inquiry Response

Goal: Quickly find and explain specific shipment status

Steps:

  1. Enter order ID in search box
  2. Click "Build Shipping Report"
  3. Review Last Status column
  4. Click tracking code link to view full details
  5. Note Shipped On and Arrived On dates
  6. If late, explain and offer resolution

Example: Customer asks about order #12345. Search shows "in_transit" status, shipped 2 days ago, estimated delivery tomorrow. Inform customer and set expectation.

Tips:

  • Use public tracking URL to share with customer
  • Note Last Checked timestamp for data freshness
  • Refresh tracking if data seems stale
  • Document any special circumstances in notes

Use Case 5: Batch Resolution of Weather Delays

Goal: Handle multiple late shipments from same carrier issue

Steps:

  1. Select affected week
  2. Filter by "Late - 3 days or more"
  3. Identify common carrier or region
  4. For each affected order, open Deal With It
  5. Use consistent notes (e.g., "Weather delay in Midwest region")
  6. Apply same action to similar cases (e.g., $5 credit)
  7. Customize email template once, reuse
  8. Process all affected orders

Example: Snowstorm delayed 25 shipments to Northeast. Apply $10 credits to all, send apology email explaining weather, maintain customer goodwill.

Tips:

  • Document external cause (weather, carrier strike, etc.)
  • Apply consistent resolution to similar cases
  • Communicate proactively before customer complains
  • Track total impact for accounting

Actions & Operations

Update Arrival Date (API Refresh)

Purpose: Pulls latest tracking data from EasyPost API

Steps:

  1. Click "updateArrivalDate" button in header
  2. Confirm action in browser dialog
  3. System queries EasyPost for current week's shipments
  4. Updates origin_scan, arrival_date, status in database
  5. May need to run multiple times for complete data
  6. Session message confirms completion

Warning:

  • Slow operation (API rate limits)
  • May timeout on very large batches
  • Run during off-peak hours if possible
  • Multiple runs may be needed for all orders

Build Shipping Report

Purpose: Generate table with current filter settings

Steps:

  1. Configure week, delivery time, and search filters
  2. Click "Build Shipping Report"
  3. Table populates with matching orders
  4. Totals section calculates aggregates
  5. Use table sorting and searching features

Export to CSV

Purpose: Download complete shipping dataset

Steps:

  1. Configure filters for desired dataset
  2. Click "Build Shipping Report"
  3. Click CSV button in report area
  4. File downloads with comprehensive columns
  5. Includes tracking codes, customer IDs, dates, status, actions, amounts

CSV Contents:

  • Order ID, Customer ID, Customer Name
  • Tracking Code, Claim Number, Claim Status
  • Public Tracking URL, Ship Method, EasyPost ID
  • Origin Scan Date, Arrival Date, Shipping Days
  • Action Taken (reship, credit, etc.), Dollar Total

File Naming: ShippingReport_[WeekDate]_[DeliveryFilter]_[Company]_[Timestamp].csv

Troubleshooting

Origin Scan Shows "5am Adjustment"

Symptoms: Red text showing "5am adjustment" under shipping date

Explanation:

  • EasyPost sometimes records pickup at midnight instead of actual time
  • System checks if origin_scan is before 5am
  • Subtracts 8 hours to adjust to likely actual pickup date
  • Prevents artificial increase in shipping days

Example: Package picked up March 5 at 11pm, recorded as March 6 at 12:01am. System adjusts back to March 5 to avoid counting extra day.

No Action Needed: This is automatic correction for accurate shipping days calculation.

Shipping Days Shows Large Negative Number

Symptoms: Shipping Days column shows -30 or other large negative

Check:

  1. Verify arrival_date is populated
  2. Check origin_scan date
  3. Confirm dates aren't swapped

Solutions:

  1. Refresh tracking data via API
  2. If data is correct, may indicate timestamp issue
  3. Contact Kiva Logic support if persistent

Common Causes:

  • Missing or corrupted date fields
  • Timezone conversion errors
  • Database migration issues

Deal With It Button Not Appearing

Symptoms: Expected "Deal With It" button missing for late shipment

Check:

  1. Verify shipment is actually late (3+ days)
  2. Check if action was already taken
  3. Confirm order meets eligibility criteria

Eligibility Criteria:

  • Must be late (failure status OR shipping_days >= 3)
  • Must have origin_scan and expected arrival
  • Est shipping days must be less than actual
  • OR must have failure status from carrier

If Eligible But Missing: Reload page, check browser console for errors, contact support.

Email Not Sending After Action

Symptoms: Clicked "Send Email" but customer didn't receive

Check:

  1. Email was queued, not sent immediately
  2. Check Email Queue (admin_email_pending.php)
  3. Verify email template exists
  4. Check customer email address is valid

Solutions:

  1. Review email queue for pending message
  2. Manually send from queue if needed
  3. Verify email templates configured
  4. Test email delivery system
  • Order Details (customer_order_info.php) - Full order and shipping information
  • Customer Info (customer_info.php) - Customer account and shipping history
  • UPS Claims (ups-claims.php) - Manage carrier claims for lost/damaged shipments
  • Email Queue (admin_email_pending.php) - View and manage outgoing emails
  • Email Templates (admin_email_edit.php) - Configure shipping notification templates

Typical Workflow:

  1. Shipping Report → Identify late shipment → Deal With It → Email customer
  2. Customer inquiry → Shipping Report search → View tracking → Explain status
  3. Shipping Report → Late shipment → Create claim → UPS Claims page

Permissions & Access

Required Access Level: View access (implied from code - no explicit permission check)

Access Level Capabilities:

  • Customer Service: View shipment status, search specific orders
  • Manager: View reports, take resolution actions, export data
  • Administrator: Full access to all features and all weeks
  • Kiva Admin: All features plus API refresh and advanced tools

Restricted Features:

  • Update Arrival Date: Generally admin only (slow operation)
  • API refresh for individual orders: All users

Best Practices

Regular Monitoring

  1. Review weekly report every Monday for previous week
  2. Handle late shipments within 48 hours
  3. Check missing data filter for tracking gaps
  4. Export monthly for carrier performance reviews

Customer Communication

  1. Proactively contact about late shipments before they ask
  2. Use consistent, professional email templates
  3. Explain carrier issues honestly
  4. Offer appropriate compensation (credit or reship)
  5. Document all communications in notes field

Data Management

  1. Refresh API data when shipments seem stale (48+ hours)
  2. Export reports before bulk API updates
  3. Document external events (weather, strikes) in notes
  4. Keep detailed records for accounting and carrier disputes

Things to Avoid

  • ❌ Don't ignore late shipments hoping customer won't notice
  • ❌ Don't run Update Arrival Date during peak business hours
  • ❌ Don't change actions without documenting why
  • ❌ Don't send generic emails - personalize for situation

Quick Reference Card

Task Action/Location
Find specific order Enter ID in search box, build report
Check current week late Week=current, Filter=Late, build
Refresh tracking data Click updateArrivalDate button
Resolve late shipment Click "Deal With It", select action
Send customer email After action, review template, send
Export data Build report, click CSV button
View full tracking Click tracking code link
Undo action Click action badge, select new action
Find missing tracking Filter=Missing data, build
Customize sort order Drag sort tiles in header area

FAQs

How often is tracking data updated?

Tracking updates when you click the refresh icon for individual orders, when you run "updateArrivalDate" for the week, or when automated processes run (if configured). It's not real-time - you must manually refresh.

What's the difference between origin_scan and ship date?

origin_scan is when the carrier first scanned the package (actual pickup). Ship date might refer to when the label was created or when you marked it for shipping, which can be different.

Can I bulk-apply actions to multiple late shipments?

Not currently - each order must be individually processed through the Deal With It modal. This ensures appropriate action and notes for each situation.

What happens if I change my mind about an action?

Click the action badge to reopen the modal. Selecting a new action will reverse the previous one (credit reversed, reship cancelled) and apply the new action.

How do claims work with carriers?

The Claim action creates a record in the ups_claims table and assigns a claim number. You'll then need to go to the UPS Claims page to complete the claim filing process with the carrier.

Change Log

2026-03-01

  • Initial documentation created
  • All sections completed based on shipping-report.php code review
  • Documented Deal With It action system
  • Added EasyPost API integration details
  • Included drag-and-drop sort configuration
  • Explained 5am adjustment logic

End of Documentation

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