Відправлення
Список методів роботи з відправленнями
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).
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.
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.
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.
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 daywhere 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
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.
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.
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:
"I want to upload a client invoice in PDF to shipment 980911" - send the base64-encoded content in "file", set
"fileName": "invoice.pdf"."I want to attach a product photo in JPEG" - encode the photo in base64, set
"fileName": "product-photo.jpeg".
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.
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.
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.
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.
Returns the stream of the file specified by fileId, if the shipment belongs to the authenticated client.
Схема (Об'єкт)
status
enum
yes
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.
Allowed: ReadyToShip
clientOrder
string
yes
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.
Constraints: Max 50 chars
note
string
yes
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.
Constraints: Max 255 chars
deliveryType
string
no
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 creation behaviour remains unchanged.
payerType
enum
yes
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 also referenced when generating an invoice.
Allowed: Sender┃Recipient┃ThirdPerson
payerContractNumber
string┃null
yes
This field is required in the following cases:
When the
payerTypeis set toThirdPerson. It must contain the payer's contract number. For clients from Ukraine, it is also acceptable to provide the tax identification number (EDRPOU) instead of the contract number.When the
payerTypeis set toSenderorRecipientand a non-cash payment method is used.
If this field is not provided in the cases described above, the payment method will automatically default to cash.
Ensure that the provided information is accurate, as it is essential for correct payment processing.
For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API.
Constraints: 2 to 20 chars
services
array
no
Contains information about additional services for the shipment.
services.shipmentParcelRowNumber
integer
yes
Specifies the row number of the parcel to which the service is applied. The value must correspond to the rowNumber of an existing parcel in the parcels array.
For services applied to the entire shipment (for example, ExpBackwardGoods), this field must be set to null.
services.serviceCode
string
yes
The code indicating the service.
A list of available codes and descriptions of their meanings:
COD— The Cash on Delivery (COD) service allows the recipient to pay for the goods directly upon receiving them, without the need for prepayment. The sender can add this service to the shipment, and the recipient has the option to pay for the goods upon delivery and inspect them before making the payment, subject to payment method restrictions established for specific countries. Available directions:Poland → Ukraine
Czech Republic → Ukraine
Germany → Ukraine
Slovakia → Ukraine
Czech Republic → Czech Republic
Poland → Poland
Germany → Germany
Romania → Moldova
🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries.
ExpBackwardGoods— Enables return delivery option for parent shipmentExpBackwardCreditDoc— Enables return delivery of signed documents for domestic document shipments within Moldova. The service is available only for legal entities and only for shipments with the Documents type. The return shipment is created as a separate document delivery (by courier or operator), and the payer is always the Recipient under a non-cash contract. Not available for Parcel Locker and PUDO service channels. In the first iteration, the service is enabled only for selected legal entities.
🔹This field is required for the services group.
services.serviceName
string
yes
Name of the service.
Allowed values include:
PaymentControl— Payment control service.MoneyTransfer— Money transfer service.Other service types available within the
servicesgroup.
🔹This field is required within the services group.
services.serviceId
string
yes
Unique identifier (reference ID) of the selected service.
This value must correspond to the service reference returned by the system. When creating or updating a shipment, the exact serviceId provided in the service reference response must be copied and used without modification.
🔹This field is required within the services group.
services.amount
number
yes
The total amount the recipient must pay under the COD service.
🔹This field is required for the services group.
services.contractNumber
string┃null
yes
Contract number of the payer responsible for the selected service. This parameter is used to identify the contractual agreement under which the service is paid.
The field is required when the service payer is a third party or when non-cash payment terms are applied. If not provided, the payment may be processed according to default billing rules.
services.payerType
string
yes
Determines who is responsible for paying for the service. The payer type determines which party bears the costs:
Recipient— The only allowed value for the COD service.Sender,Recipient— Allowed payer values for the ExpBackwardGoods service.Sender,Recipient,ThirdPerson— Allowed payer values for the BackwardDelGoods service.
🔻This field is required
services.additionalParameters
string
yes
Additional parameters for the service.
services.additionalParameters.cod
string
yes
Additional parameters for configuring COD.
🔹These parameters are mandatory and required only for the COD service
services.additionalParameters.cod.bankAccount
object
no
Information describing the bank account details to which the funds will be transferred. Includes the transfer amount, transaction currency, account identifiers, and the party responsible for paying the service fee.
services.additionalParameters.cod.bankAccount.amount
number
yes
The amount that will be transferred to the sender’s account after payment. Specifies the amount the recipient must pay upon receipt. Automatic currency conversion is possible depending on the sender's or recipient's country.
🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
services.additionalParameters.cod.bankAccount.currencyCode
string
yes
The currency for the transaction, defined by the sender’s contract. Specified according to the ISO 4217 standard.
🔸By default, the currency of the sender’s country is used, but it is possible to set the currency manually (Feature under development)/ Pattern: ^[A-Z]{3}$
services.additionalParameters.cod.bankAccount.bankAccountId
string
yes
Tax identification number of an individual or a legal entity, used for its unique identification in the system and for verifying the existence of an active contract and the availability of financial services. The same as the value passed in the companyTin field.
🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
🔸Must contain the tax identification number or equivalent identifier (EDRPOU, TIN, NIP).
services.additionalParameters.cod.bankAccount.bankAccountName
string
yes
IBAN
🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
🔸Must contain the full account number in IBAN format.
services.additionalParameters.cod.bankAccount.description
string
yes
Additional description of the payment details.
services.additionalParameters.cod.bankAccount.commissionPayer
string
yes
Specifies the party responsible for paying the commission:
RecipientSender
🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
services.additionalParameters.backwardDelivery
object
yes
Additional parameters for configuring return delivery.
🔹These parameters are mandatory and required only for the ExpBackwardGoods service
services.additionalParameters.backwardDelivery.description
string
no
Description of the goods to be returned. This value is used for informational and operational purposes during the return delivery process.
invoice
object
no
This object presents the necessary data for customs authorities to process the consignment efficiently, including the assessment of duties and taxes, and to confirm adherence to import/export regulations. The structured format of the invoice ensures that all pertinent information is easily accessible and clear, facilitating a smoother transit across borders.
Updated logic for invoice value handling. Clients must now send only two parameters in the invoice object:
cost— total declared value of the invoicecurrency— currency code of the invoice
🔸It encapsulates the invoice details, which are required for international shipments undergoing customs clearance.
invoice.customerNumber
string┃null
yes
Unique identifier/number of the invoice accompanying the goods in the shipment, generated directly by the client. It is used for customs processing (export and import clearance) because it ensures a clear link between the goods in the shipment and their accompanying documentation, including value, origin, and other necessary information for customs clearance.
If a client invoice exists in the shipment but its information is missing—specifically, its number—the shipment processing in the information system will be halted, the customs clearance period will be extended, and in the worst case, customs authorities may refuse clearance and initiate a return to the country of export.
invoice.customerCreatedAt
string
yes
You must provide the date specified in the invoice accompanying the shipment. If the date is not present in the client document, the shipment creation date may be used.
🔹This field is required if the invoice.customerNumber field is filled in.
Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
invoice.type
string
yes
Type of client invoice accompanying the shipment and used for customs declaration. This field must reflect the actual type of document enclosed in the parcel. Available values:
Invoice— commercial invoice for shipments of a commercial natureProformaInvoice— proforma invoice for shipments of a non-commercial nature
🔹This field is required if the invoice.customerNumber field is filled in.
Possible values: InvoiceProformaInvoice
invoice.incoterm
string
yes
Specifies the trade terms for the shipping agreement between the buyer and seller, based on selected standards from the Incoterms® rules. These terms define the allocation of shipping costs, insurance, customs duties, and the distribution of risk. Only a limited subset of Incoterms® is available for use:
DAP (Delivered at Place) - The recipient is responsible for import customs clearance, duties, and taxes.
DDP (Delivered Duty Paid) - The sender is responsible for import customs clearance and for paying all applicable duties and taxes.
🔹This field is required for shipments crossing the EU border or going outside the EU.
Possible values: DAP,DDP
invoice.exportReason
string
yes
Specifies the general reason for exporting items, which is required for customs and other regulatory bodies. This classification helps in understanding the type of shipment without getting into specifics. It's used to categorize shipments at a high level for smoother processing through customs. The available options are:
ForPersonalPurposes: Items are for personal use or gifts.
Selling: Items are meant for sale.
Repair: Items being sent for repair.
Return: Items are being returned to the sender or manufacturer.
Other: Any reason not covered by the other options.
🔹This field is required for shipments crossing the EU border or going outside the EU.
Possible values: ForPersonalPurposes,Selling,Repair,Return,Other
invoice.cost
number
yes
Total declared invoice value in the original currency, which must equal the sum of all invoice items calculated as (amount × cost) for each item. Used for customs and shipment declarations.
🔸If the provided cost value does not equal the sum of the cost values in the items array, it will be automatically recalculated by the system on our side.
🔸Values are validated for decimal precision, and digits beyond two decimal places are ignored.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.currency
string
yes
ISO 4217 currency code of the invoice. All items in the invoice must use the same currency.
🔹This field is required for shipments crossing the EU border or going outside the EU.
Pattern: ^[A-Z]{3}$
invoice.payerFeesCustoms
string
yes
Specifies who is responsible for paying for customs services. The parameter determines which party bears the costs:
Sender: The party sending the goods pays for the customs duties.
Recipient: The party receiving the goods is responsible for the customs duties costs.
ThirdPerson: A third party can only pay for customs services if this is permitted and the payer for delivery services is also a third party.
The default value is "Recipient". This value will also be applied automatically if the parcel exceeds the maximum allowed value (in the recipient country’s currency) for which the sender is permitted to pay customs duties.
🔹This parameter is required and valid only for the UA-EU direction.
Possible values: Sender,Recipient,ThirdPerson
invoice.items
object
yes
A detailed list of goods being shipped, including required descriptions and values, essential for customs declarations and assessing duties.
Logic: If the items block is provided, the system checks whether the total sum of all (items.cost × items.amount) matches the invoice.cost value. If not — the system updates invoice.cost to equal the sum of all items.
🔸It is required to provide this information for each individual good in the shipment in the form of an array.
invoice.items.id
string
no
A unique identifier for each item within the shipment.
🔹This field is optional.
invoice.items.hsCode
string | null
yes
The Harmonized System code for each item, a standardized numerical method of classifying traded products. This field is required for international shipments that pass through customs clearance. You can obtain the valid hsCode from the Cargo Classifiers (UKT ZED) dictionary. Validation rules:
If the sender or recipient country is Moldova (MD) or Canada (CA):
The
hsCodemust consist of exactly 10 numeric characters.If the input is longer than 10 digits, it will be truncated on the right.
If it contains fewer than 10 digits - validation error.
For all other countries:
The
hsCodemust contain between 8 and 10 numeric characters (inclusive).If fewer than 8 digits – validation error.
All non-digit characters will be stripped automatically before validation.
If the value of the
hsCodefield is210690or630900, the following conditions must be met:The
measurementCodemust be set tokg.Each item with this
hsCodemust be unique — the invoice must not contain more than one item with code210690or630900.The amount value must not exceed 10.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.items.name
string
yes
Represents the item's name in the local language, offering an accurate description for customs and logistical planning. The name should correspond with terminologies found in the Cargo Classifiers (UKT ZED) dictionary, ensuring compliance with standard classification codes. This detailed description aids in precise item identification during the customs clearance process. This field supports Unicode encoding, permitting the inclusion of special characters and symbols using the \uXXXX format. This capability allows for precise representation of item names in languages that incorporate non-Latin characters, enhancing clarity and understanding across diverse regulatory environments.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.items.nameEng
string
yes
Specifies the item's name in English, critical for ensuring that the product is identifiable and understandable across international trade and logistics channels. The English name simplifies communication and documentation processes when dealing with international partners and authorities, aiding in the seamless facilitation of global shipments. Similar to the 'name' field, this parameter also supports Unicode encoding. Using the \uXXXX format, it accommodates the accurate rendering of any special characters necessary for the correct representation of the item's name in English.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.items.material
string
no
The primary material from which the item is made, important for customs declarations and potential restrictions.
🔸If this field is not provided, the default value will be applied.
invoice.items.materialEng
string
no
The description of the item's material in English, aiding in the universal understanding of the product's composition.
🔸If this field is not provided, the default value will be applied.
invoice.items.madeInCountryCode
string | null
no
The ISO 3166-1 alpha-2 code indicating the country of manufacture, essential for determining import duties and compliance with trade agreements.
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance.
Pattern: ^[A-Z]{2}$
invoice.items.producerAndModel
string | null
no
The parameter represents the manufacturer and model of the device when creating a shipment. Both values are included in a single parameter. This parameter is mandatory for the following categories:
Electrical appliances
Laptops
Phones
Large and small household appliances
Other similar items
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance.
invoice.items.actualWeight
integer | null
yes
Actual total weight of all units of the item in grams (g).
Supported precision: 10 grams (0.01 kg). Values not divisible by 10 g are rounded down to the nearest lower multiple of 10 g.
🔸This field is mandatory when the invoice.items array is present in the request.
The system validates that the sum of actualWeight values across all invoice items matches the total shipment weight (sum of parcels[].actualWeight).
⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors.
invoice.items.measurementCode
string
yes
The unit of measurement for the item quantity, such as pieces, kilograms, meters, etc., standardizing the way quantities are reported.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.items.amount
number
yes
The quantity of the item being shipped, necessary for inventory and customs documentation. Value in the units of measurement corresponding to the field measurementCode.
🔹This field is required for shipments crossing the EU border or going outside the EU.
invoice.items.cost
number
yes
The value per single unit of the item in the sender's currency, important for insurance and customs valuation.
🔸Values are validated for decimal precision, and digits beyond two decimal places are ignored.
🔹This field is required for shipments crossing the EU border or going outside the EU.
parcels
object
yes
Parcels` description block. Array contains objects, each object responsible for information about parcel.
🔻All fields in this array must be filled.
parcels.cargoCategory
string
no
Specifies the type of the shipment, helping to categorize the goods for logistics and customs processing. The category impacts how the shipment is handled, its shipping cost, and the required documentation. Available categories are:
parcel: Small to medium-sized packages, typically for consumer goods and retail items.
documents: Postal shipments containing documents such as letters, contracts, and official papers. This category is specifically for items that weigh no more than 1 kg and have dimensions not exceeding 35 cm in length, 25 cm in width, and 2 cm in height.
pallet: Type of cargo formed as a pallet shipment with fixed dimensions and weight limits, available in the Business Cabinet of Europe for legal entities:
Up to 250 kg, area ~0.48 m², dimensions 80 × 60 × 170 cm
Up to 500 kg, area ~0.96 m², dimensions 120 × 80 × 170 cm
Up to 750 kg, area ~1.2 m², dimensions 120 × 100 × 170 cm
Up to 1000 kg, area ~1.2 m², dimensions 120 × 100 × 170 cm
Possible values: parcel,documents,pallet
parcels.parcelDescription
string
no
This field requires a concise description of the contents within the shipment, providing essential information on the nature of the items enclosed. This description aids in the logistics process, offering a clear understanding of the package contents for transportation planning and customs clearance. The summary should include details like the type of items, their purpose, and any other relevant information that describes the contents. It’s crucial for ensuring that the shipment complies with shipping regulations and facilitates smooth customs processing. Additionally, this field supports data in Unicode encoding, allowing for the inclusion of special characters and symbols using the \uXXXX format. This feature is particularly useful for languages that use non-Latin characters, ensuring accurate representation of item descriptions across diverse linguistic contexts.
parcels.insuranceCost
number
yes
Represents the declared value of the shipment for insurance coverage, in the currency of the sender's country. This value indicates the maximum compensation amount in the event of damage or loss during transit. Setting this value appropriately is crucial for ensuring adequate insurance protection. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation.
The minimum allowable value depends on the shipment direction:
UA → EU / UA → International: the value must be greater than 0 due to mandatory invoice and insurance requirements.
EU → EU: a value of 0 is permitted for shipments that do not require insurance coverage and for which no invoice is provided.
Example: 1.5
parcels.rowNumber
integer
yes
Sequential identifier for each parcel within a shipment, used to organize and track individual packages, especially when multiple items are involved. If the shipment contains only one package, the value should be 1.
parcels.width
integer
yes
The parcel's width measured in millimeters, used alongside length and height to compute the total volume for logistical planning.
parcels.length
integer
yes
The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning.
parcels.height
integer
yes
The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning.
parcels.actualWeight
integer
yes
Actual item weight in grams (g).
Supported precision: 10 grams (0.01 kg). Values not divisible by 10 g are rounded down to the nearest lower multiple of 10 g.
🔸This field is mandatory when the invoice.items array is present in the request.
The system validates that the sum of actualWeight values across all invoice items matches the total shipment weight (sum of parcels[].actualWeight).
⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors.
sender
object
yes
Information about the party sending the shipment, including details about an individual or organization responsible for the dispatch.
🔻This array of fields is required
sender.companyTin
string
yes
The tax identification number or equivalent identifier (EDRPOU, TIN, NIP, IČO - for Slovakia) of a legal entity.
🔸The fields are required for a legal entity. If they are not filled in, the sender will be considered an individual
sender.companyName
string | null
yes
The official name of the sender's company. This field is used when the sender is a business entity, helping to identify the sending organization in documentation and records.
sender.eoriCode
string | null
yes
The EORI code (Economic Operators Registration and Identification number) is used by the European Union to identify economic operators engaged in international trade. The sender's EORI code should be included in the invoice to ensure correct customs clearance and taxation when shipping goods to EU countries. The code is not mandatory but strongly recommended for international shipments to the EU, as it facilitates customs processing and helps avoid delays.
sender.phone
string
yes
The contact phone number of the sender or the sender’s company representative. It is required for shipment-related communication, including pickup coordination and issue resolution.
Format: The phone number must be provided in international format according to the E.164 standard.
Example: 380XXXXXXXXX, 491234567890, 371XXXXXXXX
Restrictions:
The sender's phone number must be valid and reachable in case of delivery issues.
If the number is submitted in a local (non-international) format, the system will attempt to normalize it, but such logic is limited and may not support all variations across countries. We strongly recommend implementing front-end validation to ensure numbers are entered in the correct international format.
🔻This field is required
sender.email
string
yes
Email address of the sender, providing an electronic means of contact for updates, inquiries, and important notifications about the shipment.
🔹This field is required for shipments crossing the EU border or going outside the EU.
sender.name
string
yes
The full name of the individual sender or the primary contact person for a company sender. This name is used in all correspondences and documents related to the shipment.
🔸Important for EU → UA international shipments: The sender name must be provided using Latin characters only. Use of Cyrillic characters (including Ukrainian letters) is not allowed and will result in validation or processing errors on the Last Mile partner side.
🔻This field is required
sender.ioss
string
no
The IOSS (Import One-Stop Shop) number is an optional input used to facilitate the VAT declaration process for shipments from non-EU countries with a declared value of up to EUR 150. It is utilized by shippers using the IOSS process to simplify customs procedures for deliveries to private customers in the EU. This field is available for shipments where the sender's country is outside the EU and the destination is within the EU.
Pattern: /^[a-zA-Z0-9]*$/u
sender.countryCode
string
yes
A two-letter code representing the sender's country, following the ISO 3166-1 Alpha-2 standard, indicating the country of origin for the shipment.
🔻This field is required
Pattern: ^[A-Z]{2}$
sender.divisionNumber
string | null
yes
This field is mandatory for parcels that are dispatched from a post office division or parcel locker, requiring the unique identifier of the dispatch location to be specified.
🔹This field is required if both the sender.addressParts group and the sender.divisionID field are missing or empty
Example: 32521/1
sender.divisionID
integer | null
yes
Division ID for specific branch identification.
🔹This field is required if both the sender.addressParts group and the sender.divisionNumber field are missing or empty
sender.addressParts
object
yes
This array of fields is required when shipping directly from an address, detailing the specific components of the location from which the parcel is dispatched. It includes detailed address information, ensuring the accurate identification of the pickup location.
sender.addressParts.city
string
yes
The name of the city from which the shipment is dispatched. It helps pinpoint the exact urban location for pickup or shipping.
🔹This field is required if sender.divisionNumber and sender.divisionID fields are missing or empty.
🔸For shipments where the sender country is Moldova or Ukraine, the sender city is validated against internal settlement directories. If the settlement cannot be resolved due to an invalid or unmapped value, the shipment will not be created.
sender.addressParts.region
string
yes
Specifies the broader administrative area, like a state or province, encompassing the city, providing additional context for the shipment's origin.
🔹This field is required for shipments when the sender or recipient country is the USA, Ireland, or Canada.
sender.addressParts.street
string
yes
Identifies the specific street address for the sender's location, crucial for accurate pickup or delivery operations.
🔹This field is required if sender.divisionNumber and sender.divisionID fields are missing or empty.
sender.addressParts.postCode
string
yes
The postal or ZIP code corresponding to the sender's address. It's essential for sorting and routing the shipment efficiently.
🔹This field is required if sender.divisionNumber and sender.divisionID fields are missing or empty.
sender.addressParts.building
string
yes
The building number or name at the specified street address, pinpointing the precise location for shipment collection.
🔹This field is required if sender.divisionNumber and sender.divisionID fields are missing or empty.
sender.addressParts.flat
string
no
If applicable, the apartment or suite number within a building from which the shipment originates, ensuring pickup personnel can locate the sender's exact unit.
sender.addressParts.block
string | null
no
Indicates a specific block or section within a larger residential area or complex, if relevant, aiding in locating the sender's precise starting point for the shipment.
sender.addressParts.note
string
no
Allows for the inclusion of additional details or instructions about the sender's address that might facilitate the pickup process, such as gate codes, specific entry points, or preferred contact times.
recipient
object
yes
Information about the party receiving the shipment, detailing either an individual or an organization responsible for receiving the dispatched goods.
🔻This array of fields is required
recipient.companyTin
string | null
yes
The tax identification number or equivalent identifier (EDRPOU, TIN, NIP, IČO - for Slovakia) of a legal entity.
🔸The fields are required for a legal entity. If they are not filled in, the recipient will be considered an individual
recipient.companyName
string | null
yes
The formal name of the recipient's company. Utilize this field when the recipient is a business entity, aiding in the identification of the receiving organization in documents and records.
recipient.eoriCode
string | null
yes
The recipient's EORI code is important for customs clearance when shipping goods to European Union countries, especially when sending to legal entities. The code is not mandatory but recommended, as it helps ensure smooth customs clearance and minimizes the risk of delays. The requirement for the recipient eoriCode depends on the type of goods being shipped:
Non-excise goods: The EORI code is not mandatory if non-excise goods are being shipped from Ukraine to a legal entity in Europe. If the recipient does not have an EORI code, one will be automatically assigned.
Excise goods: The EORI code is required for shipments of excise goods. The recipient must obtain an EORI code before the goods can be shipped.
recipient.phone
string
yes
The contact phone number of the recipient or the recipient’s company representative. Used for delivery notifications and communication with the customer during shipment processing.
Format: The phone number must be provided in international format according to the E.164 standard.
Example: 380XXXXXXXXX, 491234567890, 371XXXXXXXX
Restrictions:
For deliveries to Nova Post branches in Europe, Ukrainian mobile numbers are acceptable.
For deliveries to partner locations (such as InPost, GLS, Venipak, Cargus, etc.) and cross-border address deliveries, the phone number must belong to a mobile operator in the recipient's country. If the phone number is submitted in a local (non-international) format, the system will attempt to normalize it to the international format, but the internal algorithm does not cover all possible cases. If your system does not support front-end validation of phone numbers, we recommend informing us about failed phone number cases so we can assess potential improvements to the normalization logic.
🔻This field is required
recipient.email
string
yes
The email address of the recipient, serving as a digital contact point for shipment updates, inquiries, and essential notifications.
🔹This field is required for shipments crossing the EU border or going outside the EU.
recipient.name
string
yes
The complete name of the individual recipient or the primary contact for a company recipient. This is the name used for all shipping-related correspondence and documentation.
🔻This field is required
recipient.countryCode
string
yes
A two-letter code that identifies the recipient's country, adhering to the ISO 3166-1 Alpha-2 standard, which specifies the shipment's destination country.
🔻This field is required
Pattern: ^[A-Z]{2}$
recipient.divisionNumber
string | null
yes
This field is mandatory for parcels intended to be collected from a post office division or parcel locker, requiring the insertion of the unique identifier for the designated location.
🔹This field is required if both the recipient.addressParts group and the recipient.divisionID field are missing or empty
Example: 32521/1
recipient.divisionID
integer | null
yes
Division ID for specific branch identification.
🔹This field is required if both the recipient.addressParts group and the recipient.divisionNumber field are missing or empty
recipient.addressParts
object
yes
This array of fields is necessary when the shipment is directed to a specific address, outlining the precise location details to which the parcel is to be delivered. It encompasses comprehensive address information to ensure the exact identification of the delivery location.
🔸The values in the nested address fields must not duplicate each other. Providing the same address information in multiple inner fields will result in an error.
recipient.addressParts.city
string
yes
The city to which the shipment is being delivered. This detail ensures the parcel is directed to the correct urban area for the recipient.
🔹This field is required if recipient.divisionNumber and recipient.divisionID fields are missing or empty.
🔸For shipments where the recipient country is Moldova or Ukraine, the recipient city is validated against internal settlement directories. If the settlement cannot be resolved due to an invalid or unmapped value, the request will be rejected with the error:validation.condition.recipient_settlement_not_defined.
recipient.addressParts.region
string
yes
Specifies the recipient's state or province within the destination country, crucial for accurate shipment routing and delivery. When sending to the USA, it's essential to include a two-letter state code, such as "WA" for Washington or "DC" for the District of Columbia, according to the ISO 3166-2:US standard.
🔹This field is required for shipments when the sender or recipient country is the USA, Ireland, or Canada.
recipient.addressParts.street
string
yes
The street name of the recipient's address, vital for pinpointing the exact delivery spot.
🔹This field is required if recipient.divisionNumber and recipient.divisionID fields are missing or empty.
recipient.addressParts.postCode
string
yes
The postal or ZIP code for the recipient's address, critical for the precise sorting and routing of the parcel to its final destination.
🔹This field is required if recipient.divisionNumber and recipient.divisionID fields are missing or empty.
recipient.addressParts.building
string
yes
Specifies the building number or name at the recipient's address, guiding the delivery to the exact building within a given street.
🔹This field is required if recipient.divisionNumber and recipient.divisionID fields are missing or empty.
recipient.addressParts.flat
string
no
The apartment or suite number, if the delivery is to a multi-unit building, ensuring the parcel reaches the specific unit of the recipient.
recipient.addressParts.block
string | null
no
Identifies a block or section within a larger complex or residential area for the recipient, useful in large housing developments to further narrow down the delivery point.
recipient.addressParts.note
string
no
The space for any additional recipient-related address instructions or details that might assist in the delivery process, such as security instructions, specific doors for delivery, or preferred delivery times.
recipient.registrationAddressRecipient
object
no
The registrationAddressRecipient object provides a detailed breakdown of the recipient's registered address and is required when shipping to countries with specific customs requirements, such as Germany, Slovakia, Hungary, and France. This ensures compliance with local regulations and facilitates smooth customs processing. The object allows for a precise and complete representation of the recipient's address, which is especially important for international shipments to countries with strict customs regulations.
recipient.registrationAddressRecipient.city
string
yes
The name of the city where the recipient is registered. It must match the local naming conventions for accurate identification.
🔹This field is required for shipments to countries with specific customs requirements, including Germany, Slovakia, Hungary, and France.
recipient.registrationAddressRecipient.street
string
yes
The name of the street in the recipient's address. It must match the local naming conventions for accurate identification.
🔹This field is required for shipments to countries with specific customs requirements, including Germany, Slovakia, Hungary, and France.
recipient.registrationAddressRecipient.zipCode
string
yes
The postal code of the recipient's registered address.
🔹This field is required for shipments to countries with specific customs requirements, including Germany, Slovakia, Hungary, and France.
recipient.registrationAddressRecipient.building
string
yes
The building number or name where the recipient is registered.
🔹This field is required for shipments to countries with specific customs requirements, including Germany, Slovakia, Hungary, and France.
recipient.registrationAddressRecipient.apartment
string
no
The flat or apartment number within the building.
recipient.registrationAddressRecipient.state
string
no
The state or region where the recipient is registered. Required in some countries for detailed geographical identification.
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.
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
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.
🔹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.
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.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
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.
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
Останнє оновлення