Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Tracking shipment

BasicTracking

get
/shipments/tracking/history

This API method enables you to retrieve the status of a shipment by providing the transportation document number. By specifying the document number in the request, you can obtain information about the current location or status of the shipment, providing clients with real-time updates on the progress of their cargo. 🔸This method works only with the transportation document number (shipment number) and does not support searching by client order numbers or any external identifiers. 🔸BasicTracking provides a simplified tracking response focused on the shipment’s status history and, optionally, its related shipment numbers. Unlike FullTracking, it does not return detailed routing information, parcel-level data, undelivery reasons, return/redirect records, or extended metadata. This method is intended for quick, lightweight status checks.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
numbers[]stringOptional

Shipment`s numbers. Can accept either a single number or an array of numbers.

Example: SHPL1234567890
extendedstringOptional

Parameter responsible for including in the response an array of objects listing all related shipments.

To receive this data in the response, set the value to 1.

Default: 0Example: 1
Responses
200

Tracking response schema

application/json
get/shipments/tracking/history
GET /v.1.0/shipments/tracking/history HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "id": "111003",
      "number": "SHPL1234567890",
      "history_tracking": [
        {
          "code": "1",
          "code_name": "Zamówienie zostało utworzone. Poczekaj na wysłanie przesyłki",
          "country_code": "PL",
          "settlement": "Głogów Małopolski",
          "date": "2023-03-10T05:57:09.626014Z"
        }
      ],
      "related_numbers": [
        "SHPL2345678901"
      ]
    }
  ]
}

FullTracking

get
/shipments/tracking

This API method enables you to retrieve the status of a shipment by providing the transportation document number. By specifying the document number in the request, you can obtain information about the current location or status of the shipment, providing clients with real-time updates on the progress of their cargo.

By default, the response contains the following data blocks:

  • Current status of the shipment;

  • Tracking history;

  • Actual tracking history;

  • Description of the shipment;

  • Extended information about related shipments.

If necessary, additional blocks can be included in the response by passing the appropriate parameters:

  • withUndeliveryReason = true - adds an array of objects with information about the reasons for non-delivery of shipments.

  • withCreatedOnTheBasis = true - adds an array of objects with information about returns or forwarding associated with the shipment.

🔸FullTracking provides a comprehensive tracking response containing detailed shipment status data, full movement history, parcel descriptions, undelivery reasons, and information about related or derivative shipments. Unlike BasicTracking, it offers extended operational details and is designed for cases requiring full visibility into the shipment’s logistics lifecycle.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
numbers[]stringOptional

Shipment numbers. Can accept either a single number or an array of numbers.

Example: SHPL1234567890
ids[]integer · int32Optional

Search shipments by transportation document ids. Accepts either a single search id or an array of ids to conduct the search.

Example: 113622
withUndeliveryReasonbooleanOptional

A parameter that controls the inclusion of an array of objects containing information about non-delivery reasons in the response. To receive this data in the response, set the value to true.

Default: falseExample: true
withCreatedOnTheBasisbooleanOptional

Parameter responsible for including in the response an array of objects containing information about related shipments (types: Redirecting, Return, Utilization, Redelivery). To receive this data in the response, set the value to true.

Default: falseExample: true
countryCodestringOptional

Two-letter sender country code according to the ISO 3166-1 Alpha-2 standard. If this parameter is specified, Tracking history and Actual tracking history will be shown only for the specified country. Pattern: ^[A-Z]{2}$

Example: DE
externalstringOptional

Parameter responsible for including in the response an array of objects listing all related shipments, as well as an array containing extended information about those shipments — including the shipment owner’s name, shipment number, and shipment creation date. To receive this data in the response, set the value to 1.

Default: 0Example: 1
trackingByBarcodestringOptional

The system filters aggregated data and returns information only for the specified parcel. This allows tracking the delivery route of a specific parcel within a multi-parcel shipment.

Example: SHRO1452163509
withAllParcelsbooleanOptional

The system aggregates events from all parcel into a single array, grouped by parcel number. This allows tracking the delivery route of each parcel within a multi-parcel shipment.

Default: falseExample: true
Responses
200

Tracking response schema

application/json
alternativeNumbersstring[]Optional

An array of objects containing a list of related shipments.

get/shipments/tracking
GET /v.1.0/shipments/tracking HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "currentStatus": {
        "number": "SHPL2326420334",
        "createdDate": "2025-07-01T09:18:44.000000Z",
        "scheduledDate": "2025-07-01T15:00:00.000000Z",
        "scheduledDateOriginal": null,
        "adjustedDate": null,
        "closingDate": "2025-07-01T09:20:04.000000Z",
        "statusCode": 9,
        "status": "Delivered 01.07",
        "statusDate": "2025-07-01T09:20:11.299982Z",
        "deliveryType": "Division",
        "deliveryCountry": "DE"
      },
      "detailsTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:50.000000Z",
          "event": "Arrival",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": null,
          "settlementName": "Amsterdam",
          "eventName": "Arrived at branch 2",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "historyOnlineTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "51499647910100",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "parcelsDetailsTracking": null,
      "parcelsHistoryOnlineTracking": null,
      "parcels": [
        {
          "number": "SHPL2326420334",
          "rowNumber": null,
          "untied": false,
          "cargoCategoryGroup": "parcel",
          "cargoCategoryId": "",
          "categoryCargoName": "Parcel",
          "parcelDescription": null,
          "insuranceCost": 25,
          "insuranceCostCurrencyCode": "EUR",
          "length": 25,
          "width": 15,
          "height": 18,
          "actualWeight": 5,
          "volumetricWeight": 1.69,
          "lengthCheck": null,
          "widthCheck": null,
          "heightCheck": null,
          "actualWeightCheck": null,
          "volumetricWeightCheck": null
        }
      ],
      "alternativeNumbers": [],
      "alternativeNumbersGW": [],
      "deliveryInfo": null,
      "undeliveryReasons": [
        {
          "reasonName": "Delivery date rescheduling has been agreed with the client",
          "reasonDate": "2025-07-01T09:35:46.000000Z",
          "reasonId": "66a936c6-f223-11dd-a18e-001d92f78697",
          "subtypeOfReasonId": "c30ec884-d9ff-11ed-a361-48df37b92096",
          "subtypeOfReasonName": "Recipient does not respond / Sender rescheduled the date to"
        }
      ],
      "createdOnTheBasis": [
        {
          "number": "51499647910100",
          "type": "Redirecting",
          "createdAt": "2025-07-01T09:19:49.000000Z"
        }
      ]
    }
  ]
}
PreviousPrint documents
NextProof of delivery

Last updated