Shipments
This API method enables you to retrieve a list of transportation documents (shipments) that you have created. By making a request with this method, you can access the transportation documents that belongs to you or your account. The response will include details of each shipment, such as the shipment ID, number, recipient, cargo detail, and other relevant information.
Authorization JWT-token with a lifetime of 1 hour in header
Search shipments by transportation document number. Can accept either a single search number or an array of numbers for conducting the search.
SHPL6145344878Search shipments by transportation document ids.
113622Max number of items to return on page.
15Example: 1Number of page to return.
1Flag showing whether the shipment is included in the registry. Only for European parcels.
trueNumber of the register that lists all shipments in the registry. Only for European parcels.
CRPL0000004855DivisionId of the shipment sender.
12shipments
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 438,
"per_page": 1,
"total": 438,
"from": 1,
"to": 1,
"items": [
{
"id": "860344",
"version": 1,
"number": "SHPL9719840000",
"dateTime": "2023-11-01T10:49:39.965000Z",
"scheduledDeliveryDate": "2023-11-05T16:00:00.000000Z",
"closingDate": null,
"createdAt": "2023-11-01T10:49:41.860000Z",
"updatedAt": "2023-11-01T10:49:41.860000Z",
"deletedAt": null,
"userCreate": "6e1ad1af-6595-44ba-ba3c-a748f6c10000",
"status": "ReadyToShip",
"gtid": "2000000000000439545",
"paymentStatus": "NeedPay",
"currencyCode": "PLN",
"parcelsAmount": 1,
"note": "",
"payerType": "Sender",
"payerContractId": null,
"payerContractNumber": null,
"postomatCellReservation": "",
"postomatOrderRef": "",
"firstDayStorage": null,
"cargoAutoReturnDate": null,
"marketplacePartner": "",
"registerNumber": "",
"customerNote": "",
"creationDateNote": "",
"sender": {
"companyId": null,
"companyTin": "",
"companyName": null,
"phone": "48993450000",
"email": "example@mail.pl",
"name": "LastName Name",
"countryCode": "PL",
"settlementId": "22326",
"cityId": null,
"address": "02144, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Sasanki, 12, , 1, ",
"addressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Sasanki",
"post_code": "02144",
"building": "12",
"flat": "1",
"block": "",
"note": ""
},
"divisionId": "",
"divisionCategory": "",
"archive": false
},
"recipient": {
"companyId": null,
"companyTin": "",
"companyName": null,
"phone": "380991230000",
"email": "example@mail.com",
"name": "LastName Name",
"countryCode": "UA",
"settlementId": "127808",
"cityId": null,
"address": "36023, Україна,Полтавська область,,місто Полтава,Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО, 79,,,",
"addressParts": {
"city": "місто Полтава",
"region": "Полтавська область",
"street": "Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО",
"post_code": "36023",
"building": "79",
"flat": "",
"block": "",
"note": ""
},
"divisionId": "11664",
"divisionCategory": "PostBranch",
"archive": false
},
"parcels": [
{
"number": "SHPL9719840000",
"row_number": 1,
"untied": false,
"cargo_category_id": "2",
"cargo_category_group": "Parcel",
"parcel_description": "Example",
"insurance_cost": 30,
"length": 350,
"width": 200,
"height": 100,
"actual_weight": 2000,
"volumetric_weight": 1750,
"length_check": null,
"width_check": null,
"height_check": null,
"actual_weight_check": null,
"volumetric_weight_check": null
}
],
"services": [
{
"id": 2068473,
"shipment_parcel_row_number": null,
"service_id": "5637144594",
"service_type": "MainService",
"service_name": "Delivery/pickup by courier",
"parcel_number": "",
"payer_type": "Sender",
"amount": 1,
"price": 10,
"discount": 0,
"cost": 10,
"cost_before_check": null,
"payment_status": "NeedPay",
"additional_parameters": {
"cod": null,
"date": null,
"from": null,
"to": null,
"string": null,
"fullName": null,
"phone": null
}
},
{
"id": 2068474,
"shipment_parcel_row_number": 1,
"service_id": "5637144588",
"service_type": "InternationalServices",
"service_name": "Parcel international delivery (small)",
"parcel_number": "1",
"payer_type": "Sender",
"amount": 1,
"price": 45,
"discount": 0,
"cost": 45,
"cost_before_check": null,
"payment_status": "NeedPay",
"additional_parameters": {
"cod": null,
"date": null,
"from": null,
"to": null,
"string": null,
"fullName": null,
"phone": null
}
}
],
"onlineTracking": {
"tracking_status_code": 1,
"tracking_update_date": "2023-11-01T10:49:42.167337Z",
"short_description": "ECN created",
"long_description": "Waiting for your parcel to ship",
"info": "",
"label": "orange"
},
"tracking": [
{
"number": "SHPL9719840000",
"date": "2023-11-01T10:49:41.860000Z",
"division": "",
"settlement": "22326",
"event": "CreateID",
"event_status": "now",
"code": "1",
"division_name": "",
"settlement_name": "Warsaw",
"event_name": "Waybill prepared, waiting for the parcel"
}
],
"totalWeight": 2,
"totalInsuranceCost": 30,
"totalCost": 55,
"invoice": {
"customerNumber": "INV-001",
"customerCreatedAt": "2023-11-01T10:00:00.000000Z",
"type": "Invoice",
"incoterm": "DAP",
"exportReason": "Selling",
"cost": 30,
"currency": "EUR",
"payerFeesCustoms": "Recipient",
"items": [
{
"customerId": "1",
"hsCode": "84701000",
"name": "Calculator",
"nameEng": "Calculator",
"material": "plastic",
"materialEng": "plastic",
"madeInCountryCode": "PL",
"producerAndModel": "Casio JR15",
"actualWeight": 2000,
"measurementCode": "pieces",
"amount": 1,
"cost": 30
}
]
}
}
]
}This API method enables you to update an existing transportation document by providing the document ID and the complete set of updated data. By specifying the document ID and including all the necessary information, you can replace the old document with the new data provided in the request. The response will typically indicate the success of the update operation and may include details of the modified document.
Update restrictions:
Shipment data can be updated only while the shipment is in the
ReadyToShipstatus.Updates are allowed only if the shipment label has not been printed.
If the shipment is not in the
ReadyToShipstatus or the shipment label has already been printed, the update request will be rejected with a validation error.
Authorization JWT-token with a lifetime of 1 hour in header
Transportation document id.
113677Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
Draft: The document is in its preliminary stage, not yet finalized.Accepted: Reviewed and accepted, the document is ready for the next steps.Issued: The document has been completed and is ready for shipping.ReadyToShip: Indicates that the shipment is prepared for transport following the creation of the express waybill. Only this value can be specified when creating a shipment.Deleted: The document has been deleted from the system.Returned: The shipment has been returned to its sender.Utilized: Indicates that the physical goods associated with the transportation document have been disposed of or destroyed and the document is closed.
Represents all potential order identifiers associated with the shipment. These identifiers are set by the customer for internal tracking purposes and are crucial for tracking the shipment throughout its journey. All entered values can be tracked in the shipment's tracking system.
Any additional information or special instructions that pertain to the order can be included here. This could encompass delivery instructions, special handling requests, or other pertinent details that facilitate the handling and processing of the shipment.
Defines the tariff type to be applied to the shipment during creation or update.
standard: Standard international delivery tariff.economy: Economy international delivery tariff.express: Express international delivery tariff.
If the field is not provided, the tariff type is determined automatically according to current business rules, and the existing shipment update behaviour remains unchanged.
🔹This field is optional.
Identifies who is responsible for the payment of delivery services. The payer type determines which party bears the cost:
Sender: The party sending the goods pays for the delivery.Recipient: The party receiving the goods is responsible for the delivery cost.ThirdPerson: A third party, not the sender or recipient, pays for the delivery services. When selecting 'ThirdPerson', the field 'payerContractNumber' must be populated with the contract number of the paying party. For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API.
This field is required when the 'payerType' is set to 'ThirdPerson'. It should contain the contract number. For clients from Ukraine, it is also acceptable to provide the tax identification number (EDRPOU) instead of the contract number. Additionally, this field must be completed for the sender as the payer when non-cash transactions are used. Failure to provide this information will default the payment method to cash. Ensure the information is accurate, as it is essential for processing the payment. For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API.
The shipment has been successfully updated. This response indicates that the specified transportation document's details have been modified according to the provided input parameters.
A unique identifier assigned to each shipment, facilitating internal operations such as modifications, system searches, and deletion of shipments. The 'id' serves as a key reference for administrative and logistical processes within the delivery system, allowing precise access and management of shipment records.
The transportation document number provided to clients for tracking purposes and accessing printed forms. It also facilitates shipment searches within the system, offering a customer-friendly way to monitor shipment progress. While 'number' is used externally for tracking and documentation, it can also serve internal needs similar to 'id' for identifying shipments in certain system operations.
^[A-Z]{4}\d{10}$Estimated delivery date based on routing and service level, subject to change based on logistics and external factors.
Current status of the shipment. Initially set to ReadyToShip upon creation, indicating it's prepared for dispatch.
Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.
32.5The total number of parcels included in the shipment. This count helps in logistics planning and tracking.
The date-time when the shipment record was created in the system.
The last date-time when the shipment record was updated. Helps in tracking changes and updates made to the shipment details.
The date-time when the shipment was canceled or removed from the system. If not canceled, this field is null.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
PUT /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1537
{
"status": "ReadyToShip",
"clientOrder": "string",
"note": "string",
"payerType": "Sender",
"payerContractNumber": null,
"invoice": {
"incoterm": "DAP",
"exportReason": "Selling",
"cost": 20,
"currency": "UAH",
"payerFeesCustoms": "Sender",
"items": [
{
"customerId": 25227,
"name": "Обладнання та електрика/Складське обладнання: Калькулятори",
"nameEng": "Hardware and Electrical/Storage Equipment: Calculators",
"measurementCode": "pieces",
"hsCode": "84701000",
"producerAndModel": "Casio JR15",
"amount": 1,
"cost": 20
}
]
},
"parcels": [
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 20,
"rowNumber": 1,
"untied": false,
"width": 200,
"length": 350,
"height": 100,
"actualWeight": 2000
},
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 15,
"rowNumber": 2,
"untied": false,
"width": 215,
"length": 345,
"height": 110,
"actualWeight": 2000
},
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 20,
"rowNumber": 3,
"untied": true,
"width": 190,
"length": 340,
"height": 120,
"actualWeight": 2000
}
],
"sender": {
"companyTin": "",
"companyName": "",
"phone": 48993453453,
"email": "example@mail.pl",
"name": "Surname Name",
"ioss": null,
"countryCode": "LT",
"divisionNumber": null,
"addressParts": {
"city": "Vilnius",
"region": "Vilniaus apskritis",
"street": "Žalgirio g",
"postCode": "12546",
"building": "92",
"flat": "",
"block": "",
"note": ""
}
},
"recipient": {
"companyTin": "",
"companyName": "",
"phone": 380001234567,
"email": "example@mail.com",
"name": "Surname Name",
"countryCode": "UA",
"divisionNumber": "32521/1",
"addressParts": {}
}
}{
"id": 113677,
"number": "SHLT4009860665",
"scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
"status": "ReadyToShip",
"cost": 31,
"parcelsAmount": 1,
"createdAt": "2023-04-11T10:42:05.543380Z",
"updatedAt": "2023-04-11T10:42:05.543380Z",
"deletedAt": null
}This method allows you to delete a shipment document based on its unique identifier (ID). To successfully remove the document from the system, the request must include its ID. The response will indicate the success of the operation.
Implementation Details for Different Regions:
1. Europe:
The method primarily expects a unique ID (Ref ID) of the document.
Additionally, deletion using the shipment number (e.g.,
SHPL0123456789) is also supported.
2. Ukraine:
Deletion is supported only by Ref ID (unique identifier of the document).
Deletion using the shipment number (e.g., waybill number) is not supported.
Authorization JWT-token with a lifetime of 1 hour in header
Transportation (shipment) document id.
{"summary":"International shipment","value":456931}shipments
Datetime when the document was deleted.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
DELETE /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{ "deletedAt": "2023-04-18T11:47:19.290462Z" } Last updated