Track Package

Track package delivery status using USPS tracking number. This endpoint provides real-time tracking information including delivery status, location updates, and estimated delivery times.

POST /API/v2/track.php

Cost: $0.01 per tracking number

Rate Limit: 60 requests per minute

Batch Limit: Maximum 35 tracking numbers per request

Supported Carriers: USPS

Tracking Number Requirements

  • Minimum 5 characters per tracking number
  • Valid USPS tracking number format
  • Package must be in USPS system
  • Optional customer reference and notes per tracking number

Authentication

This endpoint requires Bearer token authentication. Include your API key in the Authorization header.

curl -X POST https://developers.labelscheap.com/API/v2/track.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{"tracking": "9400176825477902024731"}'
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://developers.labelscheap.com/API/v2/track.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_KEY',
    'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tracking' => '9400176825477902024731'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Requested-With': 'XMLHttpRequest'
}

data = {
    'tracking': '9400176825477902024731'
}

response = requests.post(
    'https://developers.labelscheap.com/API/v2/track.php',
    headers=headers,
    json=data
)

data = response.json()
fetch('https://developers.labelscheap.com/API/v2/track.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY',
        'X-Requested-With': 'XMLHttpRequest'
    },
    body: JSON.stringify({
        tracking: '9400176825477902024731'
    })
})
.then(response => response.json())
.then(data => console.log(data));

Request

This endpoint accepts a POST request with tracking information in the JSON body.

Headers

Header Required Description
Content-Type Yes Must be application/json
Authorization Yes Bearer token with your API key
X-Requested-With Yes Must be XMLHttpRequest

Request Body

Field Type Required Description
tracking array Yes Array of tracking objects (max 35)
tracking[].tracking_number string Yes USPS tracking number (minimum 5 characters)
tracking[].customer_reference string No Optional reference number for your records
tracking[].notes string No Optional notes about the tracking number

Example Request Body

{
    "tracking": [
        {
            "tracking_number": "9400176825477902024731",
            "customer_reference": "ORDER-12345"
        },
        {
            "tracking_number": "9400109699938860804872",
            "customer_reference": "ORDER-12346",
            "notes": "Priority Mail"
        },
        {
            "tracking_number": "9400111899560654568397"
        }
    ]
}

Response

The response includes detailed tracking information from USPS, including delivery status, location updates, and timestamps.

Success Response

{
    "STATUS": "success",
    "MESSAGE": "Tracking information retrieved successfully",
    "CODE": "200",
    "DATA": {
        "tracking_results": [
            {
                "tracking_number": "9400176825477902024731",
                "customer_reference": "ORDER-12345",
                "tracking_data": {
                    "TrackInfo": {
                        "@attributes": {
                            "ID": "9400176825477902024731"
                        },
                        "TrackSummary": "Delivered, Front Door/Porch",
                        "TrackDetail": [
                            "Delivered, Front Door/Porch, January 15, 2024, 2:30 pm",
                            "Out for Delivery, January 15, 2024, 8:30 am",
                            // ... more tracking details ...
                        ]
                    }
                }
            },
            {
                "tracking_number": "9400109699938860804872",
                "customer_reference": "ORDER-12346",
                "notes": "Priority Mail",
                "tracking_data": {
                    "TrackInfo": {
                        "@attributes": {
                            "ID": "9400109699938860804872"
                        },
                        "TrackSummary": "In Transit to Next Facility",
                        "TrackDetail": [
                            "In Transit to Next Facility, January 15, 2024, 6:47 pm",
                            // ... more tracking details ...
                        ]
                    }
                }
            }
        ],
        "total_amount_deducted": 0.02,
        "tracking_count": 2,
        "success_count": 2
    },
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Response Fields

Field Type Description
STATUS string Always "success" for successful requests
MESSAGE string Human-readable success message
CODE string HTTP status code as string
DATA.tracking_results array Array of tracking results for each tracking number
DATA.tracking_results[].tracking_number string The tracking number that was queried
DATA.tracking_results[].customer_reference string Customer reference if provided in request
DATA.tracking_results[].notes string Notes if provided in request
DATA.tracking_results[].tracking_data object Complete tracking information from USPS
DATA.total_amount_deducted number Total amount deducted from account balance ($0.01 per tracking number)
DATA.tracking_count number Total number of tracking numbers in request
DATA.success_count number Number of successfully tracked packages
TIMESTAMP string ISO 8601 timestamp of the response

Code Examples

Here are complete examples for different programming languages:

<?php
class LabelsCheapAPI {
    private $apiKey;
    private $baseUrl = 'https://developers.labelscheap.com/API/v2/';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function trackPackages($trackingData) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'track.php');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->apiKey,
            'X-Requested-With: XMLHttpRequest'
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'tracking' => $trackingData
        ]));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($response === false) {
            throw new Exception('cURL error: ' . curl_error($ch));
        }
        
        $data = json_decode($response, true);
        
        if ($data === null) {
            throw new Exception('Invalid JSON response');
        }
        
        return $data;
    }
    
    public function parseTrackingEvents($trackingData) {
        $events = [];
        
        if (isset($trackingData['DATA']['tracking_results'])) {
            foreach ($trackingData['DATA']['tracking_results'] as $result) {
                $trackingNumber = $result['tracking_number'];
                $trackDetails = $result['tracking_data']['TrackInfo']['TrackDetail'] ?? [];
                
                $events[$trackingNumber] = [];
                foreach ($trackDetails as $detail) {
                    $parts = explode(', ', $detail);
                    if (count($parts) >= 2) {
                        $events[$trackingNumber][] = [
                            'status' => $parts[0],
                            'date' => $parts[1],
                            'time' => isset($parts[2]) ? $parts[2] : '',
                            'location' => isset($parts[3]) ? $parts[3] : ''
                        ];
                    }
                }
            }
        }
        
        return $events;
    }
}

// Usage
try {
    $api = new LabelsCheapAPI('YOUR_API_KEY');
    
    $trackingData = [
        [
            'tracking_number' => '9400176825477902024731',
            'customer_reference' => 'ORDER-12345'
        ],
        [
            'tracking_number' => '9400109699938860804872',
            'customer_reference' => 'ORDER-12346',
            'notes' => 'Priority Mail'
        ]
    ];
    
    $tracking = $api->trackPackages($trackingData);
    
    if ($tracking['STATUS'] === 'success') {
        echo "Total Amount Deducted: $" . $tracking['DATA']['total_amount_deducted'] . "\n";
        echo "Tracking Count: " . $tracking['DATA']['tracking_count'] . "\n";
        echo "Success Count: " . $tracking['DATA']['success_count'] . "\n\n";
        
        $events = $api->parseTrackingEvents($tracking);
        foreach ($events as $trackingNumber => $trackingEvents) {
            echo "Tracking Number: " . $trackingNumber . "\n";
            echo "Events:\n";
            foreach ($trackingEvents as $event) {
                echo "- {$event['status']} on {$event['date']} {$event['time']}";
                if ($event['location']) {
                    echo " at {$event['location']}";
                }
                echo "\n";
            }
            echo "\n";
        }
    } else {
        echo "Error: " . $tracking['MESSAGE'] . "\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
import requests
import json
from datetime import datetime

class LabelsCheapAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://developers.labelscheap.com/API/v2/'
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}',
            'X-Requested-With': 'XMLHttpRequest'
        }
    
    def track_packages(self, tracking_data):
        try:
            response = requests.post(
                f'{self.base_url}track.php',
                headers=self.headers,
                json={'tracking': tracking_data},
                timeout=30
            )
            
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            raise Exception(f'Request failed: {str(e)}')
        except json.JSONDecodeError as e:
            raise Exception(f'Invalid JSON response: {str(e)}')
    
    def parse_tracking_events(self, tracking_data):
        events = {}
        
        if 'DATA' in tracking_data and 'tracking_results' in tracking_data['DATA']:
            for result in tracking_data['DATA']['tracking_results']:
                tracking_number = result['tracking_number']
                track_details = result['tracking_data']['TrackInfo']['TrackDetail']
                
                events[tracking_number] = []
                for detail in track_details:
                    parts = detail.split(', ')
                    if len(parts) >= 2:
                        events[tracking_number].append({
                            'status': parts[0],
                            'date': parts[1],
                            'time': parts[2] if len(parts) > 2 else '',
                            'location': parts[3] if len(parts) > 3 else ''
                        })
        
        return events

# Usage
try:
    api = LabelsCheapAPI('YOUR_API_KEY')
    tracking_data = [
        [
            'tracking_number' => '9400176825477902024731',
            'customer_reference' => 'ORDER-12345'
        ],
        [
            'tracking_number' => '9400109699938860804872',
            'customer_reference' => 'ORDER-12346',
            'notes' => 'Priority Mail'
        ]
    ]
    
    tracking = api.track_packages(tracking_data)
    
    if tracking['STATUS'] == 'success':
        print(f"Total Amount Deducted: ${tracking['DATA']['total_amount_deducted']}")
        print(f"Tracking Count: {tracking['DATA']['tracking_count']}")
        print(f"Success Count: {tracking['DATA']['success_count']}")
        
        events = api.parse_tracking_events(tracking)
        for tracking_number, tracking_events in events.items():
            print(f"\nTracking Number: {tracking_number}")
            print("Events:")
            for event in tracking_events:
                location_text = f" at {event['location']}" if event['location'] else ""
                print(f"- {event['status']} on {event['date']} {event['time']}{location_text}")
    else:
        print(f"Error: {tracking['MESSAGE']}")
        
except Exception as e:
    print(f"Error: {str(e)}")
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using System.Collections.Generic;
using Newtonsoft.Json;

public class TrackingEvent
{
    public string Status { get; set; }
    public string Date { get; set; }
    public string Time { get; set; }
    public string Location { get; set; }
}

public class LabelsCheapAPI
{
    private readonly string _apiKey;
    private readonly string _baseUrl = "https://developers.labelscheap.com/API/v2/";
    private readonly HttpClient _httpClient;

    public LabelsCheapAPI(string apiKey)
    {
        _apiKey = apiKey;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest");
    }

    public async Task<dynamic> TrackPackagesAsync(List<dynamic> trackingData)
    {
        try
        {
            var requestData = new { tracking = trackingData };
            var json = JsonConvert.SerializeObject(requestData);
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            
            var response = await _httpClient.PostAsync($"{_baseUrl}track.php", content);
            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonConvert.DeserializeObject(responseContent);
        }
        catch (HttpRequestException ex)
        {
            throw new Exception($"Request failed: {ex.Message}");
        }
        catch (JsonException ex)
        {
            throw new Exception($"Invalid JSON response: {ex.Message}");
        }
    }

    public Dictionary<string, List<TrackingEvent>> ParseTrackingEvents(dynamic trackingData)
    {
        var events = new Dictionary<string, List<TrackingEvent>>();
        
        try
        {
            var trackResults = trackingData.DATA.tracking_results;
            
            foreach (var result in trackResults)
            {
                var trackingNumber = result.tracking_number.ToString();
                var trackDetails = result.tracking_data.TrackInfo.TrackDetail;
                
                events[trackingNumber] = new List<TrackingEvent>();
                foreach (var detail in trackDetails)
                {
                    var detailString = detail.ToString();
                    var parts = detailString.Split(new[] { ", " }, StringSplitOptions.None);
                    
                    if (parts.Length >= 2)
                    {
                        events[trackingNumber].Add(new TrackingEvent
                        {
                            Status = parts[0],
                            Date = parts[1],
                            Time = parts.Length > 2 ? parts[2] : "",
                            Location = parts.Length > 3 ? parts[3] : ""
                        });
                    }
                }
            }
        }
        catch
        {
            // Handle parsing errors gracefully
        }
        
        return events;
    }
}

// Usage
public class Program
{
    public static async Task Main()
    {
        try
        {
            var api = new LabelsCheapAPI("YOUR_API_KEY");
            var trackingData = new List<dynamic> {
                new { tracking_number = "9400176825477902024731", customer_reference = "ORDER-12345" },
                new { tracking_number = "9400109699938860804872", customer_reference = "ORDER-12346", notes = "Priority Mail" }
            };
            
            var tracking = await api.TrackPackagesAsync(trackingData);
            
            if (tracking.STATUS == "success")
            {
                Console.WriteLine($"Total Amount Deducted: ${tracking.DATA.total_amount_deducted}");
                Console.WriteLine($"Tracking Count: {tracking.DATA.tracking_count}");
                Console.WriteLine($"Success Count: {tracking.DATA.success_count}");
                
                var events = api.ParseTrackingEvents(tracking);
                foreach (var trackingNumber in events.Keys)
                {
                    Console.WriteLine($"\nTracking Number: {trackingNumber}");
                    Console.WriteLine("Events:");
                    foreach (var evt in events[trackingNumber])
                    {
                        var locationText = !string.IsNullOrEmpty(evt.Location) ? $" at {evt.Location}" : "";
                        Console.WriteLine($"- {evt.Status} on {evt.Date} {evt.Time}{locationText}");
                    }
                }
            }
            else
            {
                Console.WriteLine($"Error: {tracking.MESSAGE}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
Imports System
Imports System.Net.Http
Imports System.Text
Imports System.Threading.Tasks
Imports System.Collections.Generic
Imports Newtonsoft.Json

Public Class TrackingEvent
    Public Property Status As String
    Public Property Date As String
    Public Property Time As String
    Public Property Location As String
End Class

Public Class LabelsCheapAPI
    Private ReadOnly _apiKey As String
    Private ReadOnly _baseUrl As String = "https://developers.labelscheap.com/API/v2/"
    Private ReadOnly _httpClient As HttpClient

    Public Sub New(apiKey As String)
        _apiKey = apiKey
        _httpClient = New HttpClient()
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}")
        _httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest")
    End Sub

    Public Async Function TrackPackagesAsync(trackingData As List(Of Object)) As Task(Of Object)
        Try
            Dim requestData = New With {.tracking = trackingData}
            Dim json = JsonConvert.SerializeObject(requestData)
            Dim content As New StringContent(json, Encoding.UTF8, "application/json")
            
            Dim response = Await _httpClient.PostAsync($"{_baseUrl}track.php", content)
            response.EnsureSuccessStatusCode()
            
            Dim responseContent = Await response.Content.ReadAsStringAsync()
            Return JsonConvert.DeserializeObject(responseContent)
        Catch ex As HttpRequestException
            Throw New Exception($"Request failed: {ex.Message}")
        Catch ex As JsonException
            Throw New Exception($"Invalid JSON response: {ex.Message}")
        End Try
    End Function

    Public Function ParseTrackingEvents(trackingData As Object) As Dictionary(Of String, List(Of TrackingEvent))
        Dim events As New Dictionary(Of String, List(Of TrackingEvent))()
        
        Try
            Dim trackResults = trackingData.DATA.tracking_results
            
            For Each result In trackResults
                Dim trackingNumber = result.tracking_number.ToString()
                Dim trackDetails = result.tracking_data.TrackInfo.TrackDetail
                
                events(trackingNumber) = New List(Of TrackingEvent)()
                For Each detail In trackDetails
                    Dim detailString = detail.ToString()
                    Dim parts = detailString.Split(New String() {", "}, StringSplitOptions.None)
                    
                    If parts.Length >= 2 Then
                        events(trackingNumber).Add(New TrackingEvent With {
                            .Status = parts(0),
                            .Date = parts(1),
                            .Time = If(parts.Length > 2, parts(2), ""),
                            .Location = If(parts.Length > 3, parts(3), "")
                        })
                    End If
                Next
            Next
        Catch
            ' Handle parsing errors gracefully
        End Try
        
        Return events
    End Function
End Class

' Usage
Public Class Program
    Public Shared Async Function Main() As Task
        Try
            Dim api As New LabelsCheapAPI("YOUR_API_KEY")
            Dim trackingData = New List(Of Object) From {
                New With {.tracking_number = "9400176825477902024731", .customer_reference = "ORDER-12345"},
                New With {.tracking_number = "9400109699938860804872", .customer_reference = "ORDER-12346", .notes = "Priority Mail"}
            }
            
            Dim tracking = Await api.TrackPackagesAsync(trackingData)
            
            If tracking.STATUS = "success" Then
                Console.WriteLine($"Total Amount Deducted: ${tracking.DATA.total_amount_deducted}")
                Console.WriteLine($"Tracking Count: {tracking.DATA.tracking_count}")
                Console.WriteLine($"Success Count: {tracking.DATA.success_count}")
                
                Dim events = api.ParseTrackingEvents(tracking)
                For Each trackingNumber In events.Keys
                    Console.WriteLine($"\nTracking Number: {trackingNumber}")
                    Console.WriteLine("Events:")
                    For Each evt In events(trackingNumber)
                        Dim locationText = If(String.IsNullOrEmpty(evt.Location), "", $" at {evt.Location}")
                        Console.WriteLine($"- {evt.Status} on {evt.Date} {evt.Time}{locationText}")
                    Next
                Next
            Else
                Console.WriteLine($"Error: {tracking.MESSAGE}")
            End If
        Catch ex As Exception
            Console.WriteLine($"Error: {ex.Message}")
        End Try
    End Function
End Class
import React, { useState, useEffect } from 'react';

const TrackingComponent = () => {
    const [trackingData, setTrackingData] = useState(null);
    const [loading, setLoading] = useState(false);
    const [error, setError] = useState(null);
    const [trackingNumbers, setTrackingNumbers] = useState('');

    const API_KEY = 'YOUR_API_KEY';
    const BASE_URL = 'https://developers.labelscheap.com/API/v2/';

    const trackPackages = async (trackingNumbers) => {
        setLoading(true);
        setError(null);

        try {
            const response = await fetch(`${BASE_URL}track.php`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${API_KEY}`,
                    'X-Requested-With': 'XMLHttpRequest'
                },
                body: JSON.stringify({
                    tracking: trackingNumbers.split(',').map(num => ({ tracking_number: num.trim() }))
                })
            });

            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }

            const data = await response.json();
            setTrackingData(data);
        } catch (err) {
            setError(err.message);
        } finally {
            setLoading(false);
        }
    };

    const parseTrackingEvents = (data) => {
        const events = {};
        
        if (data?.DATA?.tracking_results) {
            data.DATA.tracking_results.forEach(result => {
                const trackingNumber = result.tracking_number;
                const trackDetails = result.tracking_data.TrackInfo.TrackDetail;
                
                events[trackingNumber] = [];
                trackDetails.forEach(detail => {
                    const parts = detail.split(', ');
                    if (parts.length >= 2) {
                        events[trackingNumber].push({
                            status: parts[0],
                            date: parts[1],
                            time: parts[2] || '',
                            location: parts[3] || ''
                        });
                    }
                });
            });
        }
        
        return events;
    };

    const handleSubmit = (e) => {
        e.preventDefault();
        if (trackingNumbers.trim()) {
            trackPackages(trackingNumbers);
        }
    };

    return (
        <div>
            <h3>Track Packages</h3>
            
            <form onSubmit={handleSubmit}>
                <input
                    type="text"
                    value={trackingNumbers}
                    onChange={(e) => setTrackingNumbers(e.target.value)}
                    placeholder="Enter tracking numbers separated by commas"
                    required
                />
                <button type="submit" disabled={loading}>
                    {loading ? 'Tracking...' : 'Track Packages'}
                </button>
            </form>

            {error && <div className="error">Error: {error}</div>}

            {trackingData && trackingData.STATUS === 'success' && (
                <div>
                    <h4>Tracking Information</h4>
                    <p>Total Amount Deducted: ${trackingData.DATA.total_amount_deducted}</p>
                    <p>Tracking Count: {trackingData.DATA.tracking_count}</p>
                    <p>Success Count: {trackingData.DATA.success_count}</p>
                    
                    <h5>Tracking Events</h5>
                    <ul>
                        {Object.entries(parseTrackingEvents(trackingData)).map(([trackingNumber, events]) => (
                            <li key={trackingNumber}>
                                <strong>Tracking Number: {trackingNumber}</strong>
                                <ul>
                                    {events.map((event, index) => (
                                        <li key={`${trackingNumber}-${index}`}>
                                            {event.status} on {event.date} {event.time}
                                            {event.location && ` at ${event.location}`}
                                        </li>
                                    ))}
                                </ul>
                            </li>
                        ))}
                    </ul>
                </div>
            )}
        </div>
    );
};

export default TrackingComponent;
const axios = require('axios');

class LabelsCheapAPI {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://developers.labelscheap.com/API/v2/';
        this.headers = {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`,
            'X-Requested-With': 'XMLHttpRequest'
        };
    }

    async trackPackages(trackingNumbers) {
        try {
            const response = await axios.post(
                `${this.baseUrl}track.php`,
                { tracking: trackingNumbers.split(',').map(num => ({ tracking_number: num.trim() })) },
                {
                    headers: this.headers,
                    timeout: 30000
                }
            );

            return response.data;
        } catch (error) {
            if (error.response) {
                throw new Error(`HTTP ${error.response.status}: ${error.response.data?.MESSAGE || error.message}`);
            } else if (error.request) {
                throw new Error('No response received from server');
            } else {
                throw new Error(`Request failed: ${error.message}`);
            }
        }
    }

    parseTrackingEvents(trackingData) {
        const events = {};
        
        try {
            const trackResults = trackingData.DATA?.tracking_results || [];
            
            trackResults.forEach(result => {
                const trackingNumber = result.tracking_number.toString();
                const trackDetails = result.tracking_data.TrackInfo.TrackDetail;
                
                events[trackingNumber] = [];
                trackDetails.forEach(detail => {
                    const parts = detail.split(', ');
                    if (parts.length >= 2) {
                        events[trackingNumber].push({
                            status: parts[0],
                            date: parts[1],
                            time: parts[2] || '',
                            location: parts[3] || ''
                        });
                    }
                });
            });
        } catch (error) {
            console.error('Error parsing tracking events:', error);
        }
        
        return events;
    }
}

// Usage
async function main() {
    try {
        const api = new LabelsCheapAPI('YOUR_API_KEY');
        const trackingNumbers = '9400176825477902024731, 9400109699938860804872';
        
        const tracking = await api.trackPackages(trackingNumbers);

        if (tracking.STATUS === 'success') {
            console.log(`Total Amount Deducted: $${tracking.DATA.total_amount_deducted}`);
            console.log(`Tracking Count: ${tracking.DATA.tracking_count}`);
            console.log(`Success Count: ${tracking.DATA.success_count}`);
            
            const events = api.parseTrackingEvents(tracking);
            console.log('\nTracking Events:');
            Object.entries(events).forEach(([trackingNumber, trackingEvents]) => {
                console.log(`\nTracking Number: ${trackingNumber}`);
                console.log('Events:');
                trackingEvents.forEach((event, index) => {
                    const locationText = event.location ? ` at ${event.location}` : '';
                    console.log(`- ${event.status} on ${event.date} ${event.time}${locationText}`);
                });
            });
        } else {
            console.log(`Error: ${tracking.MESSAGE}`);
        }
    } catch (error) {
        console.error(`Error: ${error.message}`);
    }
}

main();

Request Tester

Test the track package endpoint with your API key:

Common Error Responses

Here are the most common error responses you might encounter:

Invalid Batch Request (422)

{
    "STATUS": "error",
    "MESSAGE": "Validation failed",
    "CODE": "422",
    "DATA": {
        "validation_errors": {
            "tracking": "Maximum 35 tracking numbers allowed per request"
        }
    },
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Invalid Tracking Number Format (422)

{
    "STATUS": "error",
    "MESSAGE": "Validation failed",
    "CODE": "422",
    "DATA": {
        "validation_errors": {
            "tracking": {
                "0": "Tracking number must be at least 5 characters"
            }
        }
    },
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Insufficient Balance (402)

{
    "STATUS": "error",
    "MESSAGE": "Insufficient balance. Required: 0.03, Available: 0.01",
    "CODE": "402",
    "DATA": [],
    "TIMESTAMP": "2024-01-15 10:30:00"
}

USPS API Unavailable (503)

{
    "STATUS": "error",
    "MESSAGE": "USPS API is currently unavailable",
    "CODE": "5001",
    "HTTP_STATUS": 503,
    "DATA": {},
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Error Handling Best Practices

  • Always validate tracking numbers before sending requests
  • Handle rate limiting by implementing exponential backoff
  • Implement retry logic for transient errors (5xx status codes)
  • Check account balance before making tracking requests
  • Display user-friendly error messages based on the error code
  • Log error details for debugging and monitoring