logistics-ops

name	logistics-ops
description	Use when an order is paid and packed and the box now has to move, go sideways, or come back — picking a carrier and service and cutting a label, reacting to a delivery exception, getting ahead of where-is-my-order tickets, running a return, exchange or refund with its reverse label, filing a carrier claim before the window closes, and setting return-window and restocking-fee policy. NOT setting stock levels or reorder points (that is `inventory`), NOT sourcing or buying from suppliers (that is `procurement`), NOT writing the apology to the customer (that is `customer-support`).
tags	["logistics","shipping","carriers","returns","reverse-logistics","fulfillment","tracking"]
recommends	["inventory","procurement","customer-support","api-connector-builder","webhooks","bookkeeping"]
origin	risco

Logistics-ops — the box is packed, now move it, watch it, and bring it home cheap

You run the parcel as an operation. An order is paid and packed; from here the box has exactly four things it can do — ship out, travel, go sideways, or come back — and your job is to make each one cost the least while keeping the promise the order made. You ship on the cheapest service that still hits the delivery date, you catch the parcel when it goes wrong before the customer notices, and you turn the return into the smallest possible revenue loss.

You do not decide what stock to hold or when to reorder — that is inventory. You do not source or buy from suppliers — that is procurement (inbound from vendors, not outbound to customers). You do not write the on-voice customer reply — you hand the facts and the trigger to customer-support and it writes the apology around them. You do not host the carrier-API webhook listener — that is api-connector-builder / webhooks. And you do not post the refund to the books — that is bookkeeping. You decide what calls to make and when, and what to do with the box.

The parcel lifecycle — the spine

Every parcel moves through four legs. Two of them (EXCEPT, REVERSE) are where operators lose money by treating them as edge cases. They are not: exceptions hit 8-12% of parcels (≈18% at peak) and returns run ≈20% of online sales. Build both as first-class paths.

  SHIP            TRACK             EXCEPT             REVERSE
  rate-shop  ──►  watch the    ──►  tiered        ──►  return / exchange /
  + cut label     tracker           response           refund + reverse label
  + validate      (event-driven)    by severity        + carrier claim
  address                              ▲                   ▲
                       └── exception ──┘                   │
                       └────────── return requested ───────┘

• SHIP — order is paid and packed; choose carrier + service against the delivery promise, validate the address, buy the label.
• TRACK — label exists; watch the tracker for status changes via webhook, not polling, and notify the customer proactively.
• EXCEPT — the tracker fired a delivery exception; classify it and respond on a severity clock.
• REVERSE — the customer wants it back / it came back damaged; run the disposition decision, cut the reverse label, file any claim.

Ship — rate-shop, don't reflex

Pick the service against the delivery promise the order actually made, not your habit. "2-day paid at checkout" sets the constraint; the cheapest service that still delivers by that date wins. Shipping everything one way leaves money on the table on every order.

Audit the surcharges — the headline is a lie. The 2026 carrier increase reads as 5.9% (UPS GRI effective 2025-12-22, FedEx 5.9% effective 2026-01-05) but lands at a real 8-12% once new dimensional/cubic criteria for Additional Handling and Large Package kick in; USPS Ground Advantage is up 7.8%, and the residential surcharge climbed ~8% into the mid-$6 range. So compare landed cost per shipment including DIM weight and surcharges, never the base rate card.

Validate the address before you buy the label. A bad/undeliverable address is the cheapest exception to prevent and the most common one to suffer — fix it at the API, not after a failed attempt.

# EasyPost: build the shipment, rate-shop, buy the cheapest that fits the promise.
shipment = client.shipment.create(
    to_address=to_addr,        # validated upstream
    from_address=from_addr,
    parcel={"length": 9, "width": 6, "height": 3, "weight": 12},  # drives DIM
)
# Filter to services that hit the promised delivery date, THEN take the cheapest.
rate = shipment.lowest_rate(carriers=["USPS", "UPS", "FedEx"])
bought = client.shipment.buy(shipment.id, rate=rate)
# `bought.tracker` is now live (pre_transit → ... → delivered).

Bad : "We always ship UPS Ground." → overpays on light zone-1 parcels,
      misses the 2-day promise, eats the surcharge increase blind.
Good: rate-shop USPS/UPS/FedEx against the 2-day promise, compare landed
      cost incl. DIM + surcharges, buy the cheapest service that still hits
      the date. Validate the address first.

Track — kill WISMO before it becomes a ticket

WISMO ("where is my order") is 30-40% of ecommerce support contacts (50%+ at peak) and each human-handled ticket costs $5-$22. The whole game is to message the customer before they message you.

Use the tracker webhook, not a polling loop. EasyPost pushes tracker.updated events as the parcel moves; subscribe and react to status changes — in_transit, out_for_delivery, exception, delivered. Polling burns API calls and lags reality. (The listener hosting is webhooks' job; you decide which events fire which message.)

The window is tiny. The difference between a handled exception and a WISMO ticket is often only 4-12 hours of response time. Fire a proactive notification on the status change and the ticket never gets created — and 98% of consumers say shipping shapes brand loyalty, so this is retention work.

You supply the trigger and the fact ("FedEx shows out-for-delivery, EDD today"). customer-support writes the tone and owns the SLA on the reply. Never let support invent an ETA the carrier hasn't given.

Except — the tiered exception protocol

A failed delivery costs ~$20-30 direct and $140+ in lost future revenue, so triage by severity, don't treat every exception the same. First normalize the code: carriers label the same event differently (FedEx, UPS, USPS each use distinct exception codes for address / weather / damage / failed-attempt — see the reference glossary), so map to a bucket before you route.

Exception type	Act on the parcel	Customer-comms SLA
Damage / past EDD	Open claim path, prep replacement/refund	Proactive outreach same business day
Address / access	Correct address, intercept, break reattempt	Resolve within 24 h
Weather / operational	Hold, let carrier recover, monitor	48-h check-in cadence
Failed attempt	Reattempt or redirect to pickup before cycle 2	Within 24 h

Sequence is always act → notify → escalate: fix the parcel first (intercept, reattempt, claim), then send the proactive message, then escalate to the carrier if the clock runs out. Don't notify before you have an action, and don't escalate before you've notified.

Claims — file before the window closes

Claim windows are hard deadlines. Miss them and the money is simply gone. Capture evidence at exception detection, because you cannot reconstruct it later.

Carrier	Damaged / missing contents	Lost / undelivered	Guaranteed-service refund
USPS	≤ 60 days from mailing*	(varies by service)	—
UPS	notice ≤ 60 days of delivery	≤ 60 days of scheduled deliv.	≤ 15 days of invoice
FedEx	≤ 60 days of ship date (intl 21 d)	up to 9 months	≤ 15 days of invoice

*Windows vary by service class; confirm against the full matrix in references before relying on a date.

Evidence checklist — gather now, at detection:

• Tracking number + the exception event/screenshot (timestamped)
• Photos of the damaged item and the packaging
• Declared/invoice value and the original label
• Weight and dimensions as shipped
• For guaranteed-service refunds: the carrier invoice (15-day clock starts there)

Reverse — turn the return into the smallest loss

Returns are ≈20% of online sales (NRF: 19.3% returned in 2025; apparel runs 20-40%), not an edge case — design the reverse flow as a primary path. Route by reason, and default to retaining revenue before handing back cash.

Return reason	Default disposition	Why
Defective / damaged	Refund or replacement, no restocking fee	Your fault — fee kills the relationship
Wrong item sent	Replacement + free reverse label	Your fault — fix fast
Changed mind / size	Instant exchange or store credit first	Retains the revenue, often cheaper than reverse freight
Not as described	Refund or store credit	Listing risk — fix the listing too
Low-value bulky	Keep-it / refund (no return)	Reverse freight > item value

Tune the policy as both a conversion lever and a cost lever. 82% of consumers rank free returns as a key purchase factor and 81% read the policy before buying — but 72% of merchants now charge a restocking fee, typically 10-25% (15-25% standard), with windows of 30-90 days. Charge the fee only where the reason is buyer-side ("changed mind"), never on a defect. And screen for fraud: ~9% of returns are fraudulent and 85% of retailers now use AI to flag them — flag mismatched weight/serial, serial returners, and wardrobing.

# The reverse label is the SAME create call with is_return: true (swaps to/from).
return_shipment = client.shipment.create(
    to_address=from_addr,      # back to your warehouse
    from_address=to_addr,      # from the customer
    parcel=parcel,
    is_return=True,
)
return_label = client.shipment.buy(
    return_shipment.id, rate=return_shipment.lowest_rate()
)

Hand the restock quantity to inventory (does it go back to sellable stock?) and the refund accounting to bookkeeping (the credit-note entry). You decide the disposition; they record the consequence.

Anti-patterns

Anti-pattern	Why it costs you	Do instead
Ship by habit, one carrier always	Overpays per order, misses promises	Rate-shop the three against the promise
Trust the "5.9%" headline	Real increase is 8-12% with DIM/surcharges	Audit landed cost per shipment
Poll the tracker on a timer	Lags reality, burns API calls	Subscribe to tracker.updated webhooks
Wait for the WISMO ticket	Ticket costs $5-22; you missed the 4-12 h window	Notify proactively on status change
Same urgency for damage and weather	Wastes effort or misses the costly one	Tier by severity (table above)
Cash-refund by default	Hands back revenue you could keep	Offer exchange / store-credit first
No return-window or restocking policy	Can't defend the cost or the conversion	Set 30-90 d window, 10-25% fee buyer-side only
Restocking fee on a defect	Burns the relationship on your own fault	Free reverse label for defective/wrong-item
Capture claim evidence "later"	Window closes, money gone; can't reconstruct	Photograph + record value/weight at detection
Let support invent the ETA	A wrong promise becomes a second complaint	Give support the tracker fact, not a guess
Treat returns as an edge case	They're ~20% of orders	Design REVERSE as a primary path

References

Full per-carrier exception-code glossary (FedEx/UPS/USPS → the four buckets), the complete claim-window matrix with required evidence per claim type, and runnable EasyPost snippets (rate-shop + one-call buy, tracker webhook handler shape, the is_return: true reverse label) live in references/carriers-and-claims.md.