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

Shipments

List of Shipment Methods
Method name
Description

Create Shipment

Create a Shipment Document. This API method is engineered to streamline the process of generating a shipping document for logistics operations through Nova Post. By submitting key data, such as the originating and destination addresses for the shipment, users can effortlessly create a document detailing the transportation of goods. This method includes optional fields for customs authorities, accommodating shipments that cross borders. The API response will provide the unique identifier of the generated document along with other relevant information.

Settlement validation rules: For shipments to or from Moldova and Ukraine, the settlement (city) must be successfully resolved. If the provided city value cannot be matched to a settlement, the request will fail with the error: validation.condition.recipient_settlement_not_defined.

Additional requirement: For shipments that require customs clearance (imports), the client invoice must be uploaded as a file through the POST /shipments/uploads/{id} method (after shipment creation).

Find Shipments List

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.

Update Shipment Document

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 ReadyToShip status.

  • Updates are allowed only if the shipment label has not been printed.

  • If the shipment is not in the ReadyToShip status or the shipment label has already been printed, the update request will be rejected with a validation error.

Delete Shipment Document

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.

Create Light Return Shipment

Creates a return shipment after the original order has been delivered. This method allows customers to create a return shipment after delivery — regardless of who handled the last mile (Nova Post or a partner).

ℹ️ Information: The return can be created only if the parent shipment has the Delivered status and includes the AllowedLightReturn service. The current status of a shipment can be found in the "items" → "statusCode" field of the Find documents method. AllowedLightReturn defines the number of days within which the recipient can initiate a return after the delivery. Internally, the system verifies several conditions before allowing a Light Return shipment to be created:

  • The parent shipment status must be one of: Issued (9, 10, 11, 106).

  • The system calculates the allowed return period using the following logic: finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day where returnDays is taken from the AllowedLightReturn service, and toTZ applies the relevant system time zone (e.g., EU region).

  • The return can be created only if the current time (nowTZ) is earlier than finalDate.

  • The system also checks that no Light Return has already been created for the same parent shipment.

If all these conditions are met, the return creation request is accepted; otherwise, the system responds with a validation error indicating why the return is not permitted.

How the Light Return Shipment works

  • The request must include one required parameter — number (the parent shipment number). All other parameters are optional.

  • The customer may specify a valid branch or address directly for the return.

  • If optional parameters are not specified, their values are automatically inherited from the parent shipment.

  • The method behavior depends on the shipment direction:

    • For UA-UA direction: the method works for parent deliveries to Postomat, PUDO, or address.

    • For EU-EU direction: the method works for parent deliveries to PUDO or address. It is not supported if the parent shipment was delivered to a Postomat.

  • If parent delivery was to an address, a pickup is created automatically. A pickup request is created only if the return wasn’t sent from a branch.

When the return is created, the system automatically generates a return waybill. For more information on creating a parent shipment, see Create documents

Calculate delivery cost

This API method allows you to calculate the estimated delivery cost and delivery time for your cargo. The delivery cost and delivery time are calculated based on factors such as weight, dimensions, destination, and shipping method. By providing the necessary details of your cargo and shipment, you can obtain an estimated cost for delivering the goods. The response will typically include the calculated cost and the scheduled delivery date based on the provided information.

Get Verification status of UA→World shipments

Returns verification statuses for international shipments for the UA→World direction (“international shipment from Ukraine to World”). Responses and errors from the core system are proxied unchanged.

Shipments uploads file

Uploads supporting documents to a specific shipment by its ID. This method is used for attaching invoices, product specifications, customs declarations, or other shipment-related documents required for processing and clearance. Files are stored and linked to the shipment, ensuring better traceability and compliance.

⚠️ Region restriction: This method is available only for European shipments (EU/EU and EU/UA directions). It is not available for shipments originating from Ukraine.

File naming: • If the "fileName" parameter is provided, the uploaded file will be stored with that name. • If "fileName" is not provided, the default file name will be set to "invoice".

Use cases:

  1. "I want to upload a client invoice in PDF to shipment 980911" - send the base64-encoded content in "file", set "fileName": "invoice.pdf".

  2. "I want to attach a product photo in JPEG" - encode the photo in base64, set "fileName": "product-photo.jpeg".

Print Shipment Documents

This API method allows you to retrieve a transportation document marking in PDF format by providing the document number. The document marking is a printable document that clients can attach or affix to their cargo when sending it. By specifying the document number in the request, you can generate a PDF file containing the document marking for easy printing.

BasicTracking

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.

FullTracking

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.

List attachments

Returns a list of available shipment-related attachment files (photos and/or signature) for the specified shipment only if the shipment belongs to the authenticated client.

Download attachment

Returns the stream of the file specified by fileId, if the shipment belongs to the authenticated client.

Shipment API Interaction Flow

Find Shipments List

get
/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.

🔹Description of control elements:

SCHEMA

Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

  • Single line description A description that fits into a single line; any text that does not fit remains hidden.

  • Multiline description An expanded description that displays more than one line of text.

EXAMPLE

Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Authorizations
AuthorizationstringRequired

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

Query parameters
numbers[]stringOptional

Search shipments by transportation document number. Can accept either a single search number or an array of numbers for conducting the search.

Example: SHPL6145344878
ids[]integer · int32Optional

Search shipments by transportation document ids.

Example: 113622
limitinteger · int32Optional

Max number of items to return on page.

Default: 15Example: 1
pageinteger · int32Optional

Number of page to return.

Example: 1
inRegistrybooleanOptional

Flag showing whether the shipment is included in the registry. Only for European parcels.

Example: true
registerNumberstringOptional

Number of the register that lists all shipments in the registry. Only for European parcels.

Example: CRPL0000004855
senderDivisionIdinteger · min: 1Optional

DivisionId of the shipment sender.

Example: 12
Responses
200

shipments

application/json
current_pageinteger · min: 1Optional

Current page.

last_pageinteger · min: 1Optional

Total pages found.

per_pageinteger · min: 1Optional

Current objects` limit for a single page.

totalintegerOptional

Total objects found.

frominteger · nullableOptional
tointeger · nullableOptional
get
/shipments

Update Shipment Document

put
/shipments/{id}

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 ReadyToShip status.

  • Updates are allowed only if the shipment label has not been printed.

  • If the shipment is not in the ReadyToShip status or the shipment label has already been printed, the update request will be rejected with a validation error.

🔹Description of control elements:

SCHEMA

Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

  • Single line description A description that fits into a single line; any text that does not fit remains hidden.

  • Multiline description An expanded description that displays more than one line of text.

EXAMPLE

Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · int32Required

Transportation document id.

Example: 113677
Body
statusstring · enumOptional

Signifies 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.
Possible values:
clientOrderstring · max: 50Optional

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.

notestring · max: 255Optional

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.

deliveryTypestringOptional

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.

payerTypestring · enumOptional

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.
Possible values:
payerContractNumberstring · min: 2 · max: 20 · nullableOptional

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.

Responses
put
/shipments/{id}

Delete Shipment Document

delete
/shipments/{id}

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.

🔹Description of control elements:

SCHEMA

Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

  • Single line description A description that fits into a single line; any text that does not fit remains hidden.

  • Multiline description An expanded description that displays more than one line of text.

EXAMPLE

Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Transportation (shipment) document id.

Example: {"summary":"International shipment","value":456931}
Responses
200

shipments

application/json
deletedAtstringOptional

Datetime when the document was deleted.

delete
/shipments/{id}
PreviousServicesNextCreate shipments

Last updated