Tracking

Create tracking request

Changed on Nov 6, 2026

Creates a tracking request for packages, postal parcels, express shipments, freight references, containers, or air waybills. Use the same tracking_number field for all of them; Parcels detects the best carrier route automatically. For reliable air waybill detection, submit NNN-NNNNNNNN with the hyphen after the airline prefix and preserve leading zeros.

Quota is counted by unique tracking_number within the current billing cycle. Re-submitting the same tracking number during that cycle does not consume another shipment from the monthly quota.

The response always includes request_id and expires_at. A request is an asynchronous lookup result, not a persistent shipment subscription; it is eligible for deletion about 30 minutes after its last update. Re-POST the same tracking number whenever you need a later refresh. If Parcels already has fresh cached data, the matching result is returned immediately with from_cache: true. If every requested shipment is cached, done is true and polling is optional. If only part of the request is cached, cached results are returned immediately and the remaining results stay in state: processing until polling or webhooks complete.

destination_country accepts an ISO-2 country code such as US or a full English country name such as United States. It is required for ordinary parcel/package numbers, but not required when carrier_hint is provided or when the tracking number is an air waybill, ISO container number, or recognized ocean bill of lading.

For carrier-specific recipient or shipment details, use postal_code, email, phone, and the documented additional_fields keys. GET /tracking-carriers publishes verified requirements using these exact request paths. Unknown or malformed additional_fields reject only the affected shipment. These values are used for the lookup and are not returned as interactive prompt events.

Pass webhook_url to receive callbacks for this request. A batch_completed webhook is also sent when the whole request is served from cache. Webhooks do not keep monitoring the shipment after that request completes; schedule a new POST with webhook_url for each later check. The create response returns a webhook secret once; store it and verify future Parcels-Signature headers.

post/trackings

Request

Base URL
https://parcelsapp.com/api-docs/mock/v4
Auth
HTTP bearer
TypeScript
https://skmtc.dev/parcelsapp/apis/parcels-api-v4/docs/trackings/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

languagestring

Response language. Defaults to en.

webhook_urlstring uri

Optional HTTPS endpoint for signed completion callbacks for this request only. This does not create a persistent shipment subscription; include the URL again in each later POST.

Example request

{
  "language": "en",
  "webhook_url": "https://example.com/parcels/webhook",
  "shipments": [
    {
      "tracking_number": "9400111206213785678901",
      "destination_country": "US",
      "carrier_hint": "usps",
      "postal_code": "78701",
      "email": "recipient@example.com",
      "phone": "+34600123456",
      "additional_fields": {
        "house_number": "12A",
        "bc_code": "5593",
        "address_key": "55-080"
      }
    }
  ]
}

Response

Tracking request created. Results can be completed from cache or still processing.

request_idstring required

Identifier for this asynchronous lookup result, not a shipment identifier or persistent monitoring subscription.

status'processing' | 'completed' required

doneboolean required

expires_atstring date-time required

Expected retention boundary for this request_id, about 30 minutes after the request's last update. It is not a delivery deadline. GET may return 404 after this time; re-POST the tracking number for a later carrier check.

Example response

{
  "request_id": "66f4f2c0e16b4c13bb7e0001",
  "status": "completed",
  "done": true,
  "expires_at": "2026-06-25T19:13:20.000Z",
  "results": [
    {
      "tracking_number": "9400111206213785678901",
      "state": "completed",
      "from_cache": true,
      "shipment": {
        "trackingId": "9400111206213785678901",
        "error": "TIMEDOUT",
        "accepted_fields": [
          "postal_code",
          "email",
          "phone"
        ],
        "status": "delivered",
        "origin": "United States",
        "destination": "United States",
        "originCode": "US",
        "destinationCode": "US",
        "fromAirport": "BRU",
        "toAirport": "DAR",
        "fromPort": "HKHKG",
        "toPort": "JPTYO",
        "pieces": 13,
        "weight": 385,
        "weight_unit": "kg",
        "volume": 1.67,
        "volume_unit": "m3",
        "flight_legs": [
          {
            "flight_number": "QR-8416",
            "origin": "DOH",
            "destination": "ALA",
            "status": "Booked",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "pieces": 34,
            "weight": 2608,
            "weight_unit": "kg",
            "volume": 32.07,
            "volume_unit": "m3"
          }
        ],
        "states": [
          {
            "state": "Delivered, In/At Mailbox",
            "location": "Austin, TX, United States",
            "date": "2026-06-25T18:42:00.000Z",
            "event_code": "DEP",
            "station": "DEL",
            "timezone": "Asia/Kolkata",
            "pieces": 13,
            "weight": 385,
            "weight_unit": "kg",
            "volume": 0.71,
            "volume_unit": "m3",
            "flight_number": "AI-2243",
            "flight_origin": "DOH",
            "flight_destination": "ALA",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "uld_number": "BT005AI"
          }
        ],
        "services": [
          {
            "slug": "usps",
            "name": "USPS"
          }
        ],
        "detectedCarrier": {
          "slug": "usps",
          "name": "USPS"
        },
        "detected": [
          0
        ],
        "attributes": [
          {
            "l": "origin",
            "val": "United States",
            "code": "US"
          }
        ],
        "externalTracking": [
          {
            "slug": "usps",
            "url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213785678901",
            "trackingId": "9400111206213785678901",
            "method": "GET"
          }
        ]
      },
      "delivery_estimate": {
        "model": {
          "version": "delivery-forecast-v1.2",
          "histogram_bucket_hours": 6
        },
        "error": {
          "minimum_sample_count": 8
        }
      }
    }
  ],
  "rejected": [
    {
      "index": 1,
      "tracking_number": "1",
      "code": "INVALID_TRACKING_NUMBER",
      "message": "tracking_number is not valid for tracking."
    }
  ],
  "webhook": {
    "url": "https://example.com/parcels/webhook",
    "secret": "whsec_abc123",
    "signature_header": "Parcels-Signature"
  }
}

Changes

Nov 6, 2026dd6315a8bc4e Revision changes
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the /// response property for the response status
- warning
  added the new INVALID_ADDITIONAL_FIELDS enum value to the // response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- warning
  added the new INVALID_CURSOR enum value to the / response property for the response status
- info
  added the new optional request property //
- info
  added the new optional request property //
- info
  added the new optional request property //
- info
  added the optional property // to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the required property to the response with the status
Jul 19, 2026f8d02f819394 Revision changes
- info
  endpoint added

Operation history