# Query tracking status by tracking no (with UTC offset)

Retrieves the current shipment tracking event, first scan tracking event, and the
complete tracking event history as reported by the carrier.


Compared to /api/shipment/tracking_by_tracking_no, this endpoint returns all
tracking event timestamps in ISO 8601 format with the UTC offset included,
allowing clients to accurately interpret local event times across different
time zones.

Endpoint: GET /api/shipment/direct/tracking_by_tracking_no
Version: v2
Security: BearerAuth

## Query parameters:

  - `tracking_no` (string, required)
    tracking number
    Example: "940013620842281000000"

  - `carrier_code` (string, required)
    carrier code
    Example: "USPS"

## Response 200 fields (application/json):

  - `code` (string)
    API response code; "ok" indicates success.
    Example: "ok"

  - `msg` (string)
    Human-readable response message.
    Example: "ok"

  - `data` (object)
    This is the latest tracking record.

  - `data.status` (string)
    Current shipment status. Possible values include:
  - created: The shipment label has been generated but not yet scanned by the carrier.  
    Indicates the shipping process has not started.
  
  - available_for_pickup: The package has arrived at a designated location and is waiting for the recipient to collect it.  
    Indicates customer action is required to retrieve the shipment.
  
  - in_transit: The package is in transit, moving through different facilities or checkpoints.  
    Indicates the shipment is on its way but has not yet reached the destination.
  
  - out_for_delivery: The package has been handed over to the courier and is on its final delivery route.  
    Indicates the shipment is in the last-mile delivery stage.
  
  - delivered: The package has been successfully delivered and signed for by the recipient.  
    Indicates the shipping process is complete.
  
  - return_to_sender: The package is being returned to the sender due to failed delivery or other issues.  
    Indicates a reverse logistics process.
  
  - voided: The shipping label has been voided and the package will not be processed.  
    Indicates the shipment has been canceled or invalidated.
  
  - error: An error occurred during shipment handling.  
    Indicates carrier-side issues that may require manual intervention.
  
  - seized_by_law_enforcement: The package was seized by law enforcement authorities.  
    Indicates compliance or legal issues affecting the shipment.
  
  - unknown: The shipment status is unknown or no valid update is available from the carrier.  
    Indicates no current tracking information.
    Enum: "created", "available_for_pickup", "in_transit", "out_for_delivery", "delivered", "return_to_sender", "voided", "error", "seized_by_law_enforcement", "unknown"

  - `data.message` (string)
    Human-readable description of the status.
    Example: "USPS in possession of item"

  - `data.scanned_time` (string)
    The timestamp when the package was scanned, returned in ISO 8601 format with the UTC offset included to indicate the local time zone.
    Example: "2025-12-16T10:48:28-05:00"

  - `data.location` (object)
    Location information reported by the carrier. Fields such as city, state, zipcode, and country may be returned depending on carrier data availability.

  - `data.location.city` (string)
    Example: "BROOKLYN"

  - `data.location.state` (string)
    Example: "NY"

  - `data.location.zipcode` (string)
    Example: 91777

  - `data.location.country` (string)

  - `data.return_to_sender` (boolean)
    Indicates whether the shipment has been returned to the sender.
This field is always present in the response when the status code is 200, regardless of the current tracking status.
- false: The shipment has not been returned to the sender.
- true: The shipment has been returned to the sender.
    Example: true

  - `data.first_scan_date` (string)
    Timestamp of the first carrier scan for the shipment, indicating when the
package was initially processed or received by the carrier. Returned in
ISO 8601 format with the UTC offset included to represent the event’s local time.
    Example: "2025-11-14T14:07:33-05:00"

  - `data.first_scan_description` (string)
    Description of the first carrier scan event. Indicates the initial status or processing message recorded when the shipment was first scanned.
    Example: "Package is in transit to a UPS facility"

  - `data.first_scan_location` (object)
    Location information reported by the carrier. Fields such as city, state, zipcode, and country may be returned depending on carrier data availability.

  - `data.tracking_events` (array)

  - `data.tracking_events.status` (string)
    Example: "in_transit"

  - `data.tracking_events.message` (string)
    Human-readable description.
    Example: "Arrived at USPS Facility"

  - `data.tracking_events.event_time` (string)
    Event timestamp returned in ISO 8601 format with the UTC offset included
to indicate the local time zone of the event.
    Example: "2025-09-15T09:22:36-05:00"