Getting started overview

Integrating WhereParcel involves a series of steps designed to enable developers to quickly begin tracking shipments across multiple carriers. The process typically starts with account creation and obtaining necessary API credentials. Following this, developers can make their first API request to verify connectivity and functionality. WhereParcel provides a free tier allowing for 50 shipments per month, which is intended for initial testing and small-scale usage.

The WhereParcel API is a RESTful API that communicates using JSON for both requests and responses. It supports common HTTP methods like GET, POST, PUT, and DELETE, with API keys used for authentication. Official SDKs are available for several programming languages, including Node.js, PHP, and Python, to streamline integration efforts.

This guide will walk through the essential steps to get WhereParcel up and running for tracking your first parcel.

Quick reference table

Step What to do Where
1. Sign Up Create a new WhereParcel account. WhereParcel Sign-up Page
2. Get API Key Locate and copy your unique API key. WhereParcel Dashboard > API Keys section
3. Choose Integration Method Select an SDK or use direct HTTP requests. WhereParcel API Reference or SDKs Documentation
4. Make First Call Send a request to track a test shipment. Your preferred development environment
5. Verify Response Check for a successful JSON response with tracking data. Your console or application logs

Create an account and get keys

To access the WhereParcel API, you must first create an account and obtain your unique API key. This key authenticates your requests and links them to your usage plan.

  1. Sign Up for a WhereParcel account: Navigate to the WhereParcel Sign-up page. Provide the required information, such as your email address and a strong password. You will typically receive an email to verify your account. Complete the verification process to activate your account.
  2. Log In to Your Dashboard: Once your account is activated, log in to the WhereParcel dashboard using your new credentials.
  3. Locate Your API Key: Within the dashboard, look for a section related to 'API Keys', 'Settings', or 'Developer Tools'. WhereParcel typically generates a primary API key for you upon account creation. Copy this key. It is crucial to treat this API key like a password, as it grants access to your WhereParcel account and associated data.
  4. Understand Key Management: While the initial key is usually sufficient, WhereParcel may offer options to generate additional keys for different applications or revoke existing ones for security purposes. Refer to the WhereParcel authentication documentation for best practices on managing your API keys.

It is recommended to store your API key securely, for instance, by using environment variables in your development environment rather than hardcoding it directly into your application's source code.

Your first request

After acquiring your API key, you can make your first tracking request. This example uses a common cURL command for simplicity, but you can adapt it to your chosen programming language using an official SDK or an HTTP client library.

API Endpoint

The primary endpoint for tracking a shipment is typically structured as follows:

POST https://api.whereparcel.com/v1/track

Request Body Example (JSON)

The request body for tracking a new shipment requires at least the tracking number and, optionally, the carrier slug if known. Specifying the carrier slug can improve tracking accuracy and speed.

{
  "tracking_number": "YOUR_TRACKING_NUMBER",
  "carrier_slug": "dhl-express" 
}

Replace "YOUR_TRACKING_NUMBER" with an actual tracking number you wish to test. For a list of supported carrier slugs, consult the WhereParcel supported carriers documentation.

Making the request with cURL

Open your terminal or command prompt and execute the following cURL command. Remember to replace YOUR_API_KEY and YOUR_TRACKING_NUMBER with your actual credentials and a valid tracking number.

curl -X POST \
  https://api.whereparcel.com/v1/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"tracking_number": "YOUR_TRACKING_NUMBER", "carrier_slug": "dhl-express"}'

If you prefer to use one of the WhereParcel SDKs, consult the specific SDK documentation for your chosen language. For example, in Node.js, an equivalent request might look like this:

const WhereParcel = require('whereparcel');
const whereparcel = new WhereParcel('YOUR_API_KEY');

whereparcel.track.create({
  tracking_number: 'YOUR_TRACKING_NUMBER',
  carrier_slug: 'dhl-express'
})
.then(trackingInfo => {
  console.log('Tracking successful:', trackingInfo);
})
.catch(error => {
  console.error('Tracking failed:', error);
});

Expected response

A successful response (HTTP status 200 OK) will return a JSON object containing the shipment's current status and detailed tracking events. The structure will vary slightly depending on the carrier and the journey stage, but it generally includes:

  • id: Unique WhereParcel ID for the shipment.
  • tracking_number: The number you provided.
  • carrier_slug: The identified carrier.
  • status: Current status (e.g., 'pending', 'in_transit', 'delivered').
  • tracking_events: An array of detailed events, including timestamps, locations, and descriptions.

Example of a successful (simplified) JSON response:

{
  "data": {
    "id": "trk_xxxxxxxxxxxx",
    "tracking_number": "YOUR_TRACKING_NUMBER",
    "carrier_slug": "dhl-express",
    "status": "in_transit",
    "last_event": {
      "description": "Processed at sorting center",
      "location": "Leipzig, Germany",
      "occurred_at": "2026-05-28T10:30:00Z"
    },
    "tracking_events": [
      {
        "description": "Shipment picked up",
        "location": "New York, US",
        "occurred_at": "2026-05-27T14:15:00Z"
      },
      {
        "description": "Processed at sorting center",
        "location": "Leipzig, Germany",
        "occurred_at": "2026-05-28T10:30:00Z"
      }
    ]
  }
}

For a complete breakdown of potential response structures and fields, refer to the WhereParcel API reference documentation for tracking responses.

Common next steps

After successfully making your first request, consider these next steps to further integrate WhereParcel:

  • Implement Webhooks: Instead of polling the API for updates, subscribe to WhereParcel webhooks. This allows WhereParcel to notify your application in real-time when a shipment's status changes, reducing API calls and improving efficiency.
  • Error Handling: Implement robust error handling in your application to gracefully manage failed requests, invalid tracking numbers, or API rate limit errors. The WhereParcel API reference on error codes provides details on common error responses.
  • Explore Additional Features: WhereParcel offers features beyond basic tracking, such as custom branding for tracking pages and automated email/SMS notifications. Investigate these options if they align with your application's requirements.
  • Optimize Carrier Detection: While providing a carrier_slug is beneficial, WhereParcel can often auto-detect the carrier. Test and understand when to provide the slug versus relying on auto-detection for optimal performance.
  • Monitor Usage: Regularly check your API usage within the WhereParcel dashboard to stay within your plan limits and anticipate any scaling needs.

Troubleshooting the first call

If your initial API call encounters issues, consider the following common troubleshooting steps:

  • Check API Key: Ensure your API key is correct and included in the Authorization: Bearer header. Typos or incorrect placement are common mistakes. Verify that no extra spaces or characters are present.
  • Verify Endpoint URL: Double-check the API endpoint URL (https://api.whereparcel.com/v1/track) for any typos or incorrect version numbers.
  • Content-Type Header: Confirm that the Content-Type: application/json header is included in your request, especially for POST requests with a JSON body. The IETF's RFC 7231 defines the standard use of the Content-Type header.
  • JSON Body Format: Validate that your JSON request body is correctly formatted. Even a missing comma or brace can cause parsing errors. Use a JSON validator if unsure.
  • Tracking Number Validity: Ensure the tracking number used in your test is valid and corresponds to an active shipment from a supported carrier.
  • Carrier Slug Accuracy: If providing a carrier_slug, verify it is accurate and matches one listed in the WhereParcel supported carriers documentation.
  • HTTP Status Codes: Pay attention to the HTTP status code returned in the API response. Common error codes include:
    • 400 Bad Request: Often indicates an issue with your request body (e.g., malformed JSON, missing required fields).
    • 401 Unauthorized: Your API key is missing or invalid.
    • 403 Forbidden: Your API key does not have permission, or your account may be suspended.
    • 404 Not Found: The endpoint URL might be incorrect, or the resource (e.g., specific tracking ID) was not found.
    • 429 Too Many Requests: You have exceeded your API rate limits.
    • 5xx Server Error: An issue on WhereParcel's side. If this persists, check the WhereParcel status page or contact support.
  • Check WhereParcel Status Page: Occasionally, API issues can stem from WhereParcel's infrastructure. Check the WhereParcel status page for any reported outages or maintenance.
  • Consult Documentation: Re-read the relevant sections of the WhereParcel API documentation, especially the examples for your chosen language or cURL.