Skip to content
Tenovi Docs

Granular Shipping Status with USPS Tracking API

Tenovi’s fulfillment webhooks provide high-level shipping status (e.g., Shipped, Delivered). For more granular, event-level tracking — such as “Out for Delivery”, “Delivery Attempted”, or “In Transit to Next Facility” — you can extract the USPS tracking number from the Tenovi tracking_link and call the USPS Tracking v3 API directly.

This recipe is useful when you need to:

  • Surface detailed delivery status in your own UI
  • Trigger workflows on specific USPS events (e.g., alert staff when delivery is attempted but fails)
  • Proactively identify stalled shipments before the patient reports a problem

Prerequisites

Section titled “Prerequisites”

Step 1 – Capture the Tracking Link from the Fulfillment Webhook

Section titled “Step 1 – Capture the Tracking Link from the Fulfillment Webhook”

When a device is shipped, Tenovi sends a fulfillment webhook with status: "Shipped" or status: "Dropshipped". The tracking_link field contains the full carrier URL.

Example fulfillment webhook payload:

{
  "hwi_device_id": "12345678-abcd-1234-abcd-1234567890ab",
  "patient_id": "patient-external-id-001",
  "hardware_uuid": "aabbcc001122",
  "sensor_code": "10",
  "device_name": "Tenovi BPM - L",
  "status": "Shipped",
  "tracking_link": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223512345670"
}

Step 2 – Extract the Tracking Number

Section titled “Step 2 – Extract the Tracking Number”

Parse the tracking number from the tracking_link URL.

Example Tracking Link

https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223512345670

Example Tracking Number

9400111899223512345670

Step 3 – Authenticate with USPS

Section titled “Step 3 – Authenticate with USPS”

The USPS Tracking v3 API uses OAuth 2.0 client credentials. Request an access token before making tracking calls. Cache this token and reuse it until it expires. Do not request a new token on every call.

Step 4 – Call the USPS Tracking v3 Endpoint

Section titled “Step 4 – Call the USPS Tracking v3 Endpoint”

See the official USPS Tracking v3 docs for full schemas and information on this endpoint. Use the Event field from TrackSummary to trigger workflows in your system.

GET https://apis.usps.com/tracking/v3/tracking/{trackingNumber}

Optional query parameters:

ParameterDescription
expand=DETAILReturns the full event history rather than just the summary

Example response (abbreviated):

{
  "TrackSummary": {
    "EventTime": "8:00 am",
    "EventDate": "October 20, 2025",
    "Event": "DELIVERED",
    "EventCity": "PORTSMOUTH",
    "EventState": "NH",
    "EventZIPCode": "03801",
    "EventCountry": "",
    "FirmName": "",
    "Name": "JOHN DOE",
    "AuthorizedAgent": "false",
    "DeliveryAttributeCode": "01"
  },
  "TrackDetail": [
    {
      "EventTime": "6:14 am",
      "EventDate": "October 20, 2025",
      "Event": "OUT FOR DELIVERY",
      "EventCity": "PORTSMOUTH",
      "EventState": "NH"
    },
    {
      "EventTime": "11:52 pm",
      "EventDate": "October 19, 2025",
      "Event": "ARRIVED AT POST OFFICE",
      "EventCity": "PORTSMOUTH",
      "EventState": "NH"
    }
  ]
}

Polling vs. Webhook-Driven Tracking

Section titled “Polling vs. Webhook-Driven Tracking”

The USPS Tracking API is a pull-based API - it does not push events to you. You have two options:

Webhook-driven polling (recommended) Poll the USPS API only after receiving a Tenovi Shipped webhook. Poll on a schedule (e.g., every 4–6 hours) until the event is DELIVERED or RETURN TO SENDER, then stop.

Scheduled polling Query all active shipments on a fixed schedule. Simpler to implement but generates unnecessary API calls for shipments that have already been delivered.

Common Issues

Section titled “Common Issues”

401 Unauthorized Your USPS access token has expired. Refresh it using the token endpoint before retrying.

Tracking number not found The package may not yet be in the USPS system. This is normal in the first few hours after the Shipped webhook fires. Retry after 4–6 hours.

Carrier is not USPS Check the domain in tracking_link. UPS links use ups.com, FedEx uses fedex.com. You will need separate integrations for each carrier.

tracking_link is null Tenovi only populates this field once the shipment has left the warehouse. If the status is Dropship Requested or Pending Shipment, the link will not yet be available.

Last updated: