| Cover image | ||
|---|---|---|
| Getting API Keys | Quick Start with the Nova Poshta API | /files/XYYn0pGahMd3pfbuTsPZ |
| Methods | Learn more about the methods and how to use them | /files/jRvCJsZxvv2mHGjdJ0O6 |
| Available integrations | Shopify and BaseLinker to quickly launch shipping | /files/4muH2LOm0ukTjZGPvXy4 |
More information about Nova Post API endpoints
#### Token Limitations * Each token is valid only for the specific API key used to generate it. * The token is valid for one hour. After expiration, a new token must be obtained to continue interacting with the API. * The maximum number of active sessions (tokens) per account may be limited by the system for security purposes. > ### Usage Recommendations > > **Refresh tokens regularly.**\ > Monitor the token expiration time and always obtain a new token before sending requests if the previous one has expired. > > **Protect your API key and token.**\ > Do not share your API key or token. Always use HTTPS for all requests to prevent data interception. > > **Monitor token usage.**\ > Track token usage to prevent system overload and mitigate potential security threats. # API Collections in Postman This is a collection of predefined requests for testing API methods, designed to simplify integration and eliminate the need to create requests manually. # Testing Test the API in the sandbox environment before going live. The collection allows safe testing without impacting production. * Test environment URL: [api-stage.novapost.pl](https://api-stage.novapost.pl/) * Separate API keys # Мethods The Methods section contains Nova Post API tools for integrating core logistics processes into external systems and automating interaction with delivery services. Methods are grouped by key integration areas: * **Authorization** — obtaining API keys and JWT tokens for authorized requests; * **Dictionaries** — access to reference data required for building valid API requests; * **Services** — additional methods for specific service scenarios; * **Shipments** — creating, updating, calculating, and managing deliveries; * **Courier delivery** — creating and managing courier pickup requests; * **Webhooks** — receiving events and status updates automatically via subscriptions; * **Fulfillment** — managing goods, stock balances, orders, and inbound operations. Each section includes endpoint descriptions, request parameters, response examples, and usage rules required for integration. ### API Collections in Postman This is a collection of predefined requests for testing API methods, designed to simplify integration and eliminate the need to create requests manually. ### SDK for PHP Applications The NovaPost API SDK is an official PHP library that simplifies integration with the Nova Post API. It provides ready-to-use methods for working with shipments, tracking, calculations, and other Nova Post services while supporting modern PHP standards and flexible customization. ### API Versioning #### Overview Nova Post uses API versioning to introduce significant changes while keeping existing client integrations stable. Each major API version is published separately in the API documentation. When a new major version becomes available, the previous version continues to operate during a transition period, allowing clients to plan and complete their migration without interrupting their services. #### Versioning Strategy We use **URL-based versioning**. The version number is included in the API endpoint path: * `https://api.novapost.com/v1.0/shipments` - current version * `https://api.novapost.com/v2.0/shipments` - future version When we release a new major version, the previous version enters a support period. Your existing integration continues to work unchanged until you are ready to migrate and to the . # SDK for PHP ## NovaPost API SDK > \The Novapost API SDK is the official PHP SDK (Software Development Kit) for integration with the Nova Post API. With this package, you can quickly and conveniently connect such Nova Post features to your PHP application as shipment creation, parcel tracking, and other services.\
\ > \Features/Advantages:\\ \php \>= 8.0\ — the package requires PHP 8.0+.\guzzlehttp/guzzle ^7.0\ — HTTP client for making requests.\psr/container ^2.0\ — compatibility with PSR dependency containers.\psr/log ^3.0\ — PSR-compliant logging interfaces.\phpstan/phpstan ^2.1\ — static analysis.\phpunit/phpunit ^9.6\ — unit tests.\squizlabs/php\_codesniffer ^3.13\ — code style/linting.\vlucas/phpdotenv ^5.6\ — loading environment variables from \.env\.\\composer require novadigital/novapost-api-sdk\\\
> \NovaPostApiFactory\.\ This allows you to quickly create a client for interacting with the Nova Post API.\ Add the following example to your code:\
> \\ use NovaDigital\NovaPost\NovaPostApiFactory; use NovaDigital\NovaPost\Exception\ApiException; use NovaDigital\NovaPost\Resources\Division;\
> $apiKey = 'YOUR\_API\_KEY';\
> try {\
> $novaPostApi = (new NovaPostApiFactory())($apiKey);\
> $searchParams = \[\
> 'textSearch' => 'berlin',\
> 'divisionCategories' => \[Division::DIVISION\_CATEGORY\_POSTOMAT]\
> ];\
> $divisions = $novaPostApi->divisions()->get($searchParams);\
> } catch (ApiException $e) {\
> echo "API Error: " . $e->getMessage();\
> } \\\
> \\ try {\
> $shipmentData = \[\
> // shipment calculation data\
> ]; $calculationResult = $novaPostApi->shipments()->calculate($shipmentData); } catch (ApiException $e) {\
> echo "API Error: " . $e->getMessage();\
> } \\\
> \\
> The SDK allows you to replace standard services (logger, HTTP client, \
> token storage, etc.) with your own implementations using the \
> \ContainerBuilder\ dependency container.\
> \
This is useful if you need to:\
\ > \\ > To do this, pass your custom services to the client factory through \ > \ContainerBuilder\.\ > \
\ > \For more flexible configuration, you can use \NovaDigital\NovaPost\DI\ContainerBuilder\ to customize different aspects of the client.\
\ use NovaDigital\NovaPost\DI\ContainerBuilder; use NovaDigital\NovaPost\Exception\ApiException; use NovaDigital\NovaPost\NovaPostApiFactory; use NovaDigital\NovaPost\Storage\JwtTokenStorageInterface; use Psr\Log\LoggerInterface; use My\Awesome\MyLogger; use My\Awesome\DbJwtTokenStorageProvider;\
> $apiKey = 'YOUR\_API\_KEY';\
> try {\
> $containerBuilder = (new ContainerBuilder())\
> ->bind(LoggerInterface::class, MyLogger::class)\
> ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);\
> \
> $novaPostApi = (new NovaPostApiFactory())(\
> apiKey: $apiKey,\
> containerBuilder: $containerBuilder\
> );\
> \
> $payload = \[\
> // calculation parameters\
> ];\
> \
> $response = $novaPostApi->shipments()->calculate($payload);\
> \
> } catch (ApiException $e) {\
> echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')';\
> } \\\
> \| Service\ | \Purpose\ | \
|---|---|
| Psr\Log\LoggerInterface\ | \Custom logging\ | \
| Psr\Http\Client\ClientInterface\ | \Custom HTTP client configuration\ | \
| NovaDigital\NovaPost\Storage\JwtTokenStorageInterface\ | \Custom JWT token storage\ | \
| NovaDigital\NovaPost\Http\ResponseHandlerInterface\ | \Custom response processing\ | \
| NovaDigital\NovaPost\Http\RetryHandlerInterface\ | \Custom retry logic\ | \
| Standard\ | \ > \Purpose\ | \ > \
|---|---|
| \PSR-4: Autoloader\\ | \ > \For class autoloading\ | \ > \
| \PSR-11: Container Interface\\ | \ > \For a flexible dependency container\ | \ > \
| \PSR-3: Logger Interface\\ | \ > \Allows using any compatible logger\ | \ > \
| \PSR-7: HTTP Message Interface\\ | \ > \Used for all API requests and responses\ | \ > \
| \PSR-18: HTTP Client\\ | \ > \For sending HTTP requests\ | \ > \
| \PSR-17: HTTP Factories\\ | \ > \For creating PSR-7 messages\ | \ > \
| \PSR-12: Extended Coding Standard\\ | \ > \For coding style\ | \ > \
The Novapost API SDK is the official PHP SDK (Software Development Kit) for integration with the Nova Post API. With this package, you can quickly and conveniently connect such Nova Post features to your PHP application as shipment creation, parcel tracking, and other services.
\nFeatures/Advantages:php >= 8.0 — the package requires PHP 8.0+.guzzlehttp/guzzle ^7.0 — HTTP client for making requests.psr/container ^2.0 — compatibility with PSR dependency containers.psr/log ^3.0 — PSR-compliant logging interfaces.phpstan/phpstan ^2.1 — static analysis.phpunit/phpunit ^9.6 — unit tests.squizlabs/php_codesniffer ^3.13 — code style/linting.vlucas/phpdotenv ^5.6 — loading environment variables from .env.composer require novadigital/novapost-api-sdkNovaPostApiFactory. This allows you to quickly create a client for interacting with the Nova Post API. Add the following example to your code:\n use NovaDigital\\NovaPost\\NovaPostApiFactory; use NovaDigital\\NovaPost\\Exception\\ApiException; use NovaDigital\\NovaPost\\Resources\\Division;\n$apiKey = 'YOUR_API_KEY';\ntry {\n $novaPostApi = (new NovaPostApiFactory())($apiKey);\n $searchParams = [\n 'textSearch' => 'berlin',\n 'divisionCategories' => [Division::DIVISION_CATEGORY_POSTOMAT]\n ];\n $divisions = $novaPostApi->divisions()->get($searchParams);\n} catch (ApiException $e) {\n echo \"API Error: \" . $e->getMessage();\n} try {\n $shipmentData = [\n // shipment calculation data\n]; $calculationResult = $novaPostApi->shipments()->calculate($shipmentData); } catch (ApiException $e) {\n echo \"API Error: \" . $e->getMessage();\n} \n The SDK allows you to replace standard services (logger, HTTP client, \n token storage, etc.) with your own implementations using the \n ContainerBuilder dependency container.\n
This is useful if you need to:
\n\n To do this, pass your custom services to the client factory through \n ContainerBuilder.\n
\nFor more flexible configuration, you can use NovaDigital\\NovaPost\\DI\\ContainerBuilder to customize different aspects of the client.
use NovaDigital\\NovaPost\\DI\\ContainerBuilder; use NovaDigital\\NovaPost\\Exception\\ApiException; use NovaDigital\\NovaPost\\NovaPostApiFactory; use NovaDigital\\NovaPost\\Storage\\JwtTokenStorageInterface; use Psr\\Log\\LoggerInterface; use My\\Awesome\\MyLogger; use My\\Awesome\\DbJwtTokenStorageProvider;\n$apiKey = 'YOUR_API_KEY';\ntry {\n $containerBuilder = (new ContainerBuilder())\n ->bind(LoggerInterface::class, MyLogger::class)\n ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);\n\n $novaPostApi = (new NovaPostApiFactory())(\n apiKey: $apiKey,\n containerBuilder: $containerBuilder\n );\n\n $payload = [\n // calculation parameters\n ];\n\n $response = $novaPostApi->shipments()->calculate($payload);\n\n} catch (ApiException $e) {\n echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')';\n} | Service | Purpose |
|---|---|
| Psr\\Log\\LoggerInterface | Custom logging |
| Psr\\Http\\Client\\ClientInterface | Custom HTTP client configuration |
| NovaDigital\\NovaPost\\Storage\\JwtTokenStorageInterface | Custom JWT token storage |
| NovaDigital\\NovaPost\\Http\\ResponseHandlerInterface | Custom response processing |
| NovaDigital\\NovaPost\\Http\\RetryHandlerInterface | Custom retry logic |
| Standard | \nPurpose | \n
|---|---|
| PSR-4: Autoloader | \nFor class autoloading | \n
| PSR-11: Container Interface | \nFor a flexible dependency container | \n
| PSR-3: Logger Interface | \nAllows using any compatible logger | \n
| PSR-7: HTTP Message Interface | \nUsed for all API requests and responses | \n
| PSR-18: HTTP Client | \nFor sending HTTP requests | \n
| PSR-17: HTTP Factories | \nFor creating PSR-7 messages | \n
| PSR-12: Extended Coding Standard | \nFor coding style | \n
| 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: 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:
|
| 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:
2. Ukraine:
|
| 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
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
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:
|
| 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:
If necessary, additional blocks can be included in the response by passing the appropriate parameters:
🔸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. |
| Create Repeat Delivery | This method creates a Repeat Delivery request for a shipment that is currently stored at a long-term storage warehouse (LTS). Key rules:
|
| Cancel Repeat Delivery | The method cancels the current active Repeat Delivery request associated with the specified shipment. Use this method when you need to cancel a repeat delivery request that has not yet been processed. Cancellation is available only while the repeat delivery order is still being processed. Key rules:
|
| Field | Type | Required | Description |
|---|---|---|---|
| status | enum | yes | Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
Allowed: |
| 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.
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:
Allowed: |
| payerContractNumber | string┃null | yes | This field is required in the following cases:
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 For services applied to the entire shipment (for example, |
| services.serviceCode | string | yes | The code indicating the service. A list of available codes and descriptions of their meanings:
🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries.
🔹This field is required for the |
| services.serviceName | string | yes | Name of the service. Allowed values include:
🔹This field is required within the |
| 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 🔹This field is required within the |
| services.amount | number | yes | The total amount the recipient must pay under the COD service. 🔹This field is required for the |
| 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:
🔻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.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 🔹This field is required for the 🔸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 🔸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:
🔹This field is required for the |
| 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:
🔸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. Constraints: Max 50 chars |
| 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 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:
🔹This field is required if the Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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 🔸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. Constraints: Min 0┃Max 9999999.99 |
| 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:
The default value is "Recipient". 🔹This parameter is required and valid only for the UA-EU direction. Possible values: |
| 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 ( 🔸It is required to provide this information for each individual good in the shipment in the form of an array. |
| invoice.items.customerId | string | no | Client item identifier. 🔹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
🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 255 chars |
| 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. Constraints: Max 512 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 512 chars |
| 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. Constraints: Max 50 chars |
| 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. Constraints: Max 255 chars |
| 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:
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance. Constraints: Max 255 chars |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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. Constraints: Max 255 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Min 0┃Max 9999999.99 |
| 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. Constraints: Min 0┃Max 9999999.99 |
| 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:
Possible values: |
| 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. Constraints: Max 255 chars |
| parcels.insuranceCost | number | yes | Represents the declared value of the shipment for insurance coverage. This value indicates the maximum compensation amount in the event of damage or loss during transit. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation. Currency handling:
🔸When The value must always be greater than 0, regardless of the shipment direction." Example: |
| parcels.insuranceCurrencyCode | string | no | ISO 4217 currency code for the declared insurance value (
🔹This field is optional." Pattern: ^[A-Z]{3}$ |
| 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. Constraints: Min 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. Constraints: Min 1 |
| parcels.length | integer | yes | The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning. Constraints: Min 1 |
| parcels.height | integer | yes | The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning. Constraints: Min 1 |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: 3 to 17 chars |
| 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:
🔻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: 🔻This field is required Constraints: Max 100 chars |
| 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. Constraints: Max 12 chars 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 Example: |
| sender.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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:
Constraints: 3 to 17 chars |
| 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:
🔻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 Constraints: Max 100 chars |
| 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 Example: |
| recipient.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| recipient.registrationAddressRecipient.apartment | string | no | The flat or apartment number within the building. Constraints: Max 10 chars |
| recipient.registrationAddressRecipient.state | string | no | The state or region where the recipient is registered. Required in some countries for detailed geographical identification. Constraints: Max 100 chars |
| Field | Type | Required | Description |
|---|---|---|---|
| status | enum | yes | Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
Allowed: |
| 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.
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:
Allowed: |
| payerContractNumber | string┃null | yes | This field is required in the following cases:
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 For services applied to the entire shipment (for example, |
| services.serviceCode | string | yes | The code indicating the service. A list of available codes and descriptions of their meanings:
🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries.
🔹This field is required for the |
| services.serviceName | string | yes | Name of the service. Allowed values include:
🔹This field is required within the |
| 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 🔹This field is required within the |
| services.amount | number | yes | The total amount the recipient must pay under the COD service. 🔹This field is required for the |
| 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:
🔻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.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 🔹This field is required for the 🔸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 🔸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:
🔹This field is required for the |
| 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:
🔸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. Constraints: Max 50 chars |
| 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 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:
🔹This field is required if the Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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 🔸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. Constraints: Min 0┃Max 9999999.99 |
| 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:
The default value is "Recipient". 🔹This parameter is required and valid only for the UA-EU direction. Possible values: |
| 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 ( 🔸It is required to provide this information for each individual good in the shipment in the form of an array. |
| invoice.items.customerId | string | no | Client item identifier. 🔹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
🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 255 chars |
| 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. Constraints: Max 512 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 512 chars |
| 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. Constraints: Max 50 chars |
| 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. Constraints: Max 255 chars |
| 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:
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance. Constraints: Max 255 chars |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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. Constraints: Max 255 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Min 0┃Max 9999999.99 |
| 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. Constraints: Min 0┃Max 9999999.99 |
| 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:
Possible values: |
| 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. Constraints: Max 255 chars |
| parcels.insuranceCost | number | yes | Represents the declared value of the shipment for insurance coverage. This value indicates the maximum compensation amount in the event of damage or loss during transit. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation. Currency handling:
🔸When The value must always be greater than 0, regardless of the shipment direction." Example: |
| parcels.insuranceCurrencyCode | string | no | ISO 4217 currency code for the declared insurance value (
🔹This field is optional." Pattern: ^[A-Z]{3}$ |
| 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. Constraints: Min 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. Constraints: Min 1 |
| parcels.length | integer | yes | The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning. Constraints: Min 1 |
| parcels.height | integer | yes | The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning. Constraints: Min 1 |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: 3 to 17 chars |
| 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:
🔻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: 🔻This field is required Constraints: Max 100 chars |
| 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. Constraints: Max 12 chars 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 Example: |
| sender.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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:
Constraints: 3 to 17 chars |
| 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:
🔻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 Constraints: Max 100 chars |
| 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 Example: |
| recipient.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| recipient.registrationAddressRecipient.apartment | string | no | The flat or apartment number within the building. Constraints: Max 10 chars |
| recipient.registrationAddressRecipient.state | string | no | The state or region where the recipient is registered. Required in some countries for detailed geographical identification. Constraints: Max 100 chars |
| Field | Type | Required | Description |
|---|---|---|---|
| status | enum | yes | Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
Allowed: |
| 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.
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:
Allowed: |
| payerContractNumber | string┃null | yes | This field is required in the following cases:
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 For services applied to the entire shipment (for example, |
| services.serviceCode | string | yes | The code indicating the service. A list of available codes and descriptions of their meanings:
🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries.
🔹This field is required for the |
| services.serviceName | string | yes | Name of the service. Allowed values include:
🔹This field is required within the |
| 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 🔹This field is required within the |
| services.amount | number | yes | The total amount the recipient must pay under the COD service. 🔹This field is required for the |
| 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:
🔻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.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 🔹This field is required for the 🔸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 🔸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:
🔹This field is required for the |
| 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:
🔸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. Constraints: Max 50 chars |
| 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 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:
🔹This field is required if the Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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 🔸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. Constraints: Min 0┃Max 9999999.99 |
| 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:
The default value is "Recipient". 🔹This parameter is required and valid only for the UA-EU direction. Possible values: |
| 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 ( 🔸It is required to provide this information for each individual good in the shipment in the form of an array. |
| invoice.items.customerId | string | no | Client item identifier. 🔹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
🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 255 chars |
| invoice.items.serialNumber | string┃null | no | Serial number of the device or equipment. This value can be used to identify the item during the Light Return process. Constraints: Max 20 chars |
| 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. Constraints: Max 512 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 512 chars |
| 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. Constraints: Max 50 chars |
| 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. Constraints: Max 255 chars |
| 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:
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance. Constraints: Max 255 chars |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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. Constraints: Max 255 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Min 0┃Max 9999999.99 |
| 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. Constraints: Min 0┃Max 9999999.99 |
| 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:
Possible values: |
| 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. Constraints: Max 255 chars |
| parcels.insuranceCost | number | yes | Represents the declared value of the shipment for insurance coverage. This value indicates the maximum compensation amount in the event of damage or loss during transit. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation. Currency handling:
🔸When The value must always be greater than 0, regardless of the shipment direction." Example: |
| parcels.insuranceCurrencyCode | string | no | ISO 4217 currency code for the declared insurance value (
🔹This field is optional." Pattern: ^[A-Z]{3}$ |
| 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. Constraints: Min 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. Constraints: Min 1 |
| parcels.length | integer | yes | The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning. Constraints: Min 1 |
| parcels.height | integer | yes | The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning. Constraints: Min 1 |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: 3 to 17 chars |
| 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:
🔻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: 🔻This field is required Constraints: Max 100 chars |
| 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. Constraints: Max 12 chars 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 Example: |
| sender.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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:
Constraints: 3 to 17 chars |
| 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:
🔻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 Constraints: Max 100 chars |
| 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 Example: |
| recipient.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| recipient.registrationAddressRecipient.apartment | string | no | The flat or apartment number within the building. Constraints: Max 10 chars |
| recipient.registrationAddressRecipient.state | string | no | The state or region where the recipient is registered. Required in some countries for detailed geographical identification. Constraints: Max 100 chars |
| Field | Type | Required | Description |
|---|---|---|---|
| status | enum | yes | Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
Allowed: |
| 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.
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:
Allowed: |
| payerContractNumber | string┃null | yes | This field is required in the following cases:
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 For services applied to the entire shipment (for example, |
| services.serviceCode | string | yes | The code indicating the service. A list of available codes and descriptions of their meanings:
🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries.
🔹This field is required for the |
| services.serviceName | string | yes | Name of the service. Allowed values include:
🔹This field is required within the |
| 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 🔹This field is required within the |
| services.amount | number | yes | The total amount the recipient must pay under the COD service. 🔹This field is required for the |
| 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:
🔻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.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 🔹This field is required for the 🔸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 🔸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:
🔹This field is required for the |
| 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:
🔸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. Constraints: Max 50 chars |
| 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 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:
🔹This field is required if the Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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:
🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: |
| 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 🔸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. Constraints: Min 0┃Max 9999999.99 |
| 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:
The default value is "Recipient". 🔹This parameter is required and valid only for the UA-EU direction. Possible values: |
| 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 ( 🔸It is required to provide this information for each individual good in the shipment in the form of an array. |
| invoice.items.customerId | string | no | Client item identifier. 🔹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
🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 255 chars |
| 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. Constraints: Max 512 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 512 chars |
| 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. Constraints: Max 50 chars |
| 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. Constraints: Max 255 chars |
| 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:
🔸This field is not required; however, shipments with this field filled are given priority during customs clearance. Constraints: Max 255 chars |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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. Constraints: Max 255 chars |
| 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 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Min 0┃Max 9999999.99 |
| 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. Constraints: Min 0┃Max 9999999.99 |
| 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:
Possible values: |
| 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. Constraints: Max 255 chars |
| parcels.insuranceCost | number | yes | Represents the declared value of the shipment for insurance coverage. This value indicates the maximum compensation amount in the event of damage or loss during transit. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation. Currency handling:
🔸When The value must always be greater than 0, regardless of the shipment direction." Example: |
| parcels.insuranceCurrencyCode | string | no | ISO 4217 currency code for the declared insurance value (
🔹This field is optional." Pattern: ^[A-Z]{3}$ |
| 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. Constraints: Min 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. Constraints: Min 1 |
| parcels.length | integer | yes | The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning. Constraints: Min 1 |
| parcels.height | integer | yes | The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning. Constraints: Min 1 |
| 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 ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647 |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: 3 to 17 chars |
| 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:
🔻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: 🔻This field is required Constraints: Max 100 chars |
| 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. Constraints: Max 12 chars 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 Example: |
| sender.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 20 chars |
| 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. Constraints: Max 100 chars |
| 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:
Constraints: 3 to 17 chars |
| 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:
🔻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 Constraints: Max 100 chars |
| 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 Example: |
| recipient.divisionID | integer | null | yes | Division ID for specific branch identification. 🔹This field is required if both the Constraints: Min 1 |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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 Constraints: Max 100 chars |
| 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 Constraints: Max 10 chars |
| 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 Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 100 chars |
| 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. Constraints: Max 10 chars |
| 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. Constraints: Max 100 chars |
| recipient.registrationAddressRecipient.apartment | string | no | The flat or apartment number within the building. Constraints: Max 10 chars |
| recipient.registrationAddressRecipient.state | string | no | The state or region where the recipient is registered. Required in some countries for detailed geographical identification. Constraints: Max 100 chars |
The available payment methods depend on the customer's status. If the sender is:
This option is available for all delivery destinations.
| | Payment by the Recipient: The availability of the service depends on the direction of delivery | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |The payer is a legal entity that has a contract with Nova Post and the appropriate permissions to pay for services as a third party. This payer is neither the sender nor the recipient.
The third party can be designated as the payer either by the company creating the shipment on behalf of its clients, or by clients who have an agreement with the legal entity to cover delivery costs. This service is convenient for corporate clients, partners, or marketplaces that want to cover delivery costs for their clients or partners.
To enable this option, clients must contact their Nova Post manager.
| ### Field Descriptions for Configuring the Payment Method **`payerType`** defines who is responsible for paying for delivery services. Possible values: * `Sender:` The sender pays for the delivery * `Recipient:` The recipient pays for the delivery * `ThirdPerson:` A third party pays for the delivery\ \ If this option is selected, the payerContractNumber field must be filled in. payerContractNumber is mandatory: * When `ThirdPerson` is selected as the payer type. 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 `Sender` or `Recipient` is selected as the payer type, and a non-cash payment method is used. If this information is not provided, the payment method will automatically default to cash.| Message | Description |
|---|---|
| "Invalid JSON format" | The request body (for POST/PUT/PATCH/DELETE methods) has an invalid JSON format. Check the request body syntax. |
| "Internal TypeError error" | An internal request-processing error on the service side. If it persists, contact support. |
| Message | Description |
|---|---|
| "Unauthenticated." | The request was sent without authorization: the Authorization header is missing the Bearer token. Add a valid token. |
| "Invalid token" | The authorization token is invalid or corrupted. Obtain a new token and retry. |
| "Expired token" | The authorization token has expired. Obtain a new token and retry. |
| "Unauthorized" | The token failed authorization (access denied). Obtain a new token. |
| "Cid profile not found" | No client profile was found for the provided token. Make sure you authorize under a correct account. |
| Message | Description |
|---|---|
| "Access denied to this registry" | You do not have permission to print this registry. Printing is available only to the client who owns the registry (access is verified by company TIN or phone number). Make sure the registry was created under your account. |
| Message | Description |
|---|---|
| "not_found" | The requested resource or route was not found. Depending on the method, this means: an unknown API key; a missing print result; the cargo classifier is unavailable; or an invalid identifier in the path (a UUID is expected). |
| "Document not found" | The verification-status method did not find a document for the parameters provided. Check the number or identifier of the international shipment. |
| "No shipments found in registry" | The registry contains no shipments eligible for marking-label printing. Add at least one shipment to the registry before printing. |
| "Registry PDF is corrupted." | The printable registry form was generated, but the resulting PDF file is empty or corrupted. Try printing again later; if the error persists, contact support. |
| "Registry not found" | The registry to print was not found for the specified identifier. Check the registry id and make sure it exists and belongs to you. |
| "Registry print not found." | The printable form for the international (MEN) registry could not be retrieved — the service returned no document content. Try again later. |
| "Shipment not found" | The shipment was not found for the specified number (tracking and marking-label printing methods). Check that the shipment number is correct. |
| "Shipments not found" | No shipments were found for the request parameters for tracking. Check the list of numbers or identifiers. |
| "This request cannot be deleted" | A courier pickup request with the specified identifier was not found among your active requests, so it cannot be deleted. Check the pickup request identifier. |
| "This request cannot be updated" | A courier pickup request with the specified identifier was not found among those available for editing. Only your own pickup requests in the Draft status can be updated. |
| "shipment not found" | The shipment was not found for the specified number while creating a claim or uploading files to it. Check that the shipment number is correct. |
| "shipment_not_found" | The shipment was not found for the specified number while retrieving a claim. Check that the shipment number is correct. |
| "shipments not found" | No shipments were found for the specified parameters for printing. Check the list of numbers or identifiers. |
| Message | Description |
|---|---|
| "Method Not Allowed" | The HTTP method is not supported by this route (for example, POST instead of GET). Check the request method. |
| Message | Description |
|---|---|
| "Cid profile timeout" | A temporary error occurred while retrieving the client profile during authorization. Try again later. |
| "Cid profile not found" | The client profile could not be retrieved during authorization. Try again later or check the account. |
| "<error text from the customs-fees service>" | An error occurred while retrieving customs fees: the source service returned an error, and its text is inserted into the message. The cause depends on the text — most often an invalid country or request parameters. |
| "Address not found" | The address-search method found no option matching your query. Refine or add detail to the search query (for example, add a city or street). |
| "Auth user don't have companyTins" | To create a subscription of the legal (company) type, your profile must have at least one company TIN, but none was found. Make sure the account is linked to a company. |
| "CID profile can not be created" | The test client profile required to issue a test API key could not be created. Try again later or contact support. |
| "Cannot save more than 100 shipments" | A single registry cannot contain more than 100 shipments. Reduce the number of shipments in the request or split them across several registries. |
| "CompanyTins not exists in auth user" | The company TINs (companyTins) passed in the request do not belong to your profile. Use only the TINs registered under your account. |
| "Country code '<countryCode>' is not allowed." | Fulfillment is not available for the country code specified in the path (countryCode). Make sure you use a supported country. The actual country code is inserted into the message. |
| "Duplicate file names" | The invoice-file upload request contains at least two files with the same name. File names must be unique within the request. |
| "Empty response from tracking service" | The test webhook call received no response from the tracking service, so the check was not completed. Try again later. |
| "File not found" | The dictionary file (the list of settlements where issuance is prohibited) is currently missing from storage. Try again later. |
| "Incorrect params for generate url" | The link to the divisions dictionary file could not be generated: there is no matching file for the requested export type. Check the request parameters. |
| "Invalid customer input format" | The customerInput value was recognized neither as a shipment number (EU format) nor as a recipient identification code. Check the format of the value provided. |
| "Invalid or unsupported countryCode. Supported values: UA, MD" | The countryCode parameter is missing or has an unsupported value. Only UA and MD are allowed for this method. |
| "Invalid response from NovaDoc." | The printable invoice was generated, but the electronic document-management service did not accept the document for signing (it returned no document identifier). Try again later. |
| "Jwt creation is not allowed, api key status is <status>" | A token cannot be issued for this API key because the key is inactive. An active key has the ACTIVE status; the current status is inserted into the message. Contact your manager to activate the key. |
| "Missing file data" | The invoice-file upload request is missing mandatory file data (type or content). Make sure both the metadata and the file content are provided. |
| "Operation not available" | Marking-label printing is not available for the identifier provided: the id list contains a value in UUID format, whereas the method expects a numeric identifier or a shipment number. |
| "Parent shipment not found or status not allowed." | A Light Return cannot be created: the parent (original) shipment was not found, or its status does not allow a return — it has not yet been delivered to the recipient. |
| "Phone number must include the country code" | The phone number was provided without a country code. Provide the number in international format with the country code (for example, +380...). |
| "Registry has no shipments" | Printing is not possible: the registry contains no shipments. |
| "Registry not found" | The registry was not found or does not belong to your profile. Renaming, adding, and removing shipments are available only for your own registries. Check the registry id. |
| "Response error" | Customs fees could not be retrieved: a communication error with the source service or an invalid response from it. Try again later. |
| "Shipment not found" | While verifying access rights for registry printing, one of the registry's shipments was not found. Check the registry contents. |
| "System is required" | The invoice-file upload request does not specify the source system for the upload. Provide the mandatory upload parameters. |
| "Test keys are available only for test envs" | The test API key issuance method works only in test environments and is not available in the production environment. |
| "The service is temporarily unavailable" | The registry could not be created: the operation is temporarily unavailable for the specified sender country. Try again later. |
| "The specified document numbers [...] do not belong to the current user and must be excluded from the request." | Some of the shipment numbers in the request do not belong to your profile. Such numbers are listed in the message text — exclude them from the request and retry. |
| "This request cannot be fulfilled" | The registry operation cannot be performed: the registry was not found, does not belong to you, has not been loaded yet, or contains no shipments for this action. Check the registry id and its contents. |
| "This request cannot be saved" | The request with shipments cannot be saved: invalid identifiers were provided (a UUID is expected) or none of the shipments belong to your profile. Check the list of shipments. |
| "This request cannot be updated" | The courier pickup request cannot be updated: for a country other than Ukraine, an id in UUID format was provided in the path, whereas a different identifier format is expected. |
| "Unable to process" | The invoice file was provided in two modes at once (both as a file and as base64). Use only one method of passing the file. |
| "Unsupported file extension in files.{n}.metadata.name" | The invoice file has an unsupported extension (specified in the files.{n}.metadata.name field). Upload only files of the allowed types. |
| "Vip not found in Ukraine" | The client was not found for the specified API key. Check that the key is correct. |
| "change_not_available" | The invoice files for this shipment cannot be changed because of its current status. The operation is available only while the shipment is in the ReadyToShip or Draft status. |
| "deletion not allowed" | Only the sender can delete a shipment. If you are not the sender, deletion is not available. |
| "document_not_belong_to_user" | A Light Return cannot be created: the specified shipment does not belong to your profile. |
| "impossible_create_light_return" | A Light Return is not available for shipments within Ukraine unless a third party is specified as the payer (payerType = ThirdPerson). |
| "impossible_create_return" | Return creation is not available for shipments sent from Ukraine. |
| "no_attachments_found_for_the specified_shipment" | The specified shipment has no attached files. |
| "no_attachments_found_for_this_shipment" | The requested file (fileId) does not belong to this shipment's attachments. Check the file identifier. |
| "not_found" | No shipment was found for the identification code provided. Check that the code is correct. |
| "print fail" | The printable registry form could not be generated. Try printing again later. |
| "shipment_was_deleted" | This shipment has already been deleted, so it cannot be deleted again. |
| "you_are_not_authorized_to_access_this_shipment" | Access to the shipment is denied: you are neither its sender nor its recipient. |
| "address.latitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "address.longitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "barcodes.{n}": "validation.document_number_format" | Invalid shipment number format. |
| "bottomLeftLatitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "bottomLeftLongitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "countryCode": "validation.country_code" | Invalid country code. Expected ISO 3166-1 alpha-2 format (e.g. UA, PL). |
| "countryCodes.{n}": "validation.country_code" | Invalid country code. Expected ISO 3166-1 alpha-2 format (e.g. UA, PL). |
| "customerInput": "validation.customer_input_format" | Invalid customer identifier format. |
| "customerPhone": "validation.phone" | The phone number does not match the international format (it must include the country code, e.g. +380...). |
| "excludeCountryCode": "validation.country_code" | Invalid country code. Expected ISO 3166-1 alpha-2 format (e.g. UA, PL). |
| "id": "validation.not_integer_or_uuid" | The identifier must be an integer or a valid UUID. |
| "invoice.items": "validation.items.*.currency.must_be_same" | All invoice items must use the same currency. |
| "invoice.items.{n}.hsCode": "validation.hsCode.length" | Invalid length of the UKT ZED (HS) code. |
| "latitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "longitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "menNumber": "validation.document_number_format" | Invalid shipment number format. |
| "number": "validation.document_number_format" | Invalid shipment number format. |
| "numbers": "validation.document_number_format" | Invalid shipment number format. |
| "phone": "validation.phone" | The phone number does not match the international format (it must include the country code, e.g. +380...). |
| "recipientPhone": "validation.phone" | The phone number does not match the international format (it must include the country code, e.g. +380...). |
| "senderPhone": "validation.phone" | The phone number does not match the international format (it must include the country code, e.g. +380...). |
| "shipmentNumber": "validation.document_number_format" | Invalid shipment number format. |
| "shipments": "validation.array" | The value must be an array. |
| "topRightLatitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "topRightLongitude": "validation.range.not_in_range" | The coordinate value is out of the allowed range (latitude −90…90, longitude −180…180). |
| "COD": "The c o d field must be true or false." | The value must be a boolean: true or false. |
| "UUIDs": "The UUIDs field is required." | Required field — must be present in the request. |
| "UUIDs": "The UUIDs field must be an array." | The value must be an array. |
| "UUIDs": "The UUIDs field must have at least 1 items." | The array must contain at least 1 item(s). |
| "UUIDs.{n}": "The UUIDs.{n} field is required." | Required field — must be present in the request. |
| "UUIDs.{n}": "The UUIDs.{n} field must be a valid UUID." | The value must be a valid UUID. |
| "activeOnDate": "The active on date field must match the format Y-m-d\TH:i:s.u\Z." | The value must match the ISO 8601 date-time format in UTC, e.g. 2026-07-21T12:00:00.000Z. |
| "actualDeliveryDateFrom": "The actual delivery date from field must be a date before or equal to actual delivery date to." | The value must be a date no later than actual delivery date to. |
| "actualDeliveryDateFrom": "The actual delivery date from field must be a string." | The value must be a string. |
| "actualDeliveryDateFrom": "The actual delivery date from field must have a value." | The field is present but empty — provide a value. |
| "actualDeliveryDateTo": "The actual delivery date to field must be a string." | The value must be a string. |
| "actualDeliveryDateTo": "The actual delivery date to field must have a value." | The field is present but empty — provide a value. |
| "additionalParameters": "The additional parameters field must be an array." | The value must be an array. |
| "additionalParameters.marketplaceDelivery": "The additional parameters.marketplace delivery field must be a string." | The value must be a string. |
| "additionalParameters.partnerPaymentData": "The additional parameters.partner payment data field must be an array." | The value must be an array. |
| "additionalParameters.partnerPaymentData.currencyCode": "The additional parameters.partner payment data.currency code field must be a string." | The value must be a string. |
| "additionalParameters.partnerPaymentData.payerType": "The additional parameters.partner payment data.payer type field must be a string." | The value must be a string. |
| "additionalParameters.partnerPaymentData.payerType": "The selected additional parameters.partner payment data.payer type is invalid." | The value is not among the allowed values for this field. |
| "additionalParameters.partnerPaymentData.paymentForm": "The additional parameters.partner payment data.payment form field must be a string." | The value must be a string. |
| "additionalParameters.partnerPaymentData.paymentForm": "The selected additional parameters.partner payment data.payment form is invalid." | The value is not among the allowed values for this field. |
| "additionalParameters.partnerPaymentData.totalCost": "The additional parameters.partner payment data.total cost field must be a number." | The value must be a number (decimals allowed). |
| "additionalParameters.paymentForm": "The additional parameters.payment form field must be a string." | The value must be a string. |
| "additionalParameters.paymentForm": "The selected additional parameters.payment form is invalid." | The value is not among the allowed values for this field. |
| "additionalParameters.recipientAddressLineRaw": "The additional parameters.recipient address line raw field must be a string." | The value must be a string. |
| "additionalParameters.recipientAddressLineRaw": "The additional parameters.recipient address line raw field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "additionalPhotos": "The additional photos field must be an array." | The value must be an array. |
| "additionalPhotos.{n}": "The additionalPhotos.{n} field must be a file of type: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml." | The file must be one of the following types: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml. |
| "additionalPhotos.{n}": "The additionalPhotos.{n} field must be a string." | The value must be a string. |
| "additionalPhotos.{n}": "The additionalPhotos.{n} field must not be greater than 4096 kilobytes." | The file size must not exceed 4096 KB. |
| "address": "The address field is required." | Required field — must be present in the request. |
| "address": "The address field must be a string." | The value must be a string. |
| "address": "The address field must be an array." | The value must be an array. |
| "address": "The address field must be at least 2 characters." | The string must be at least 2 characters long. |
| "address": "The address field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "address.latitude": "The address.latitude field is required when address is present." | Required when address is provided. |
| "address.latitude": "The address.latitude field must be a number." | The value must be a number (decimals allowed). |
| "address.longitude": "The address.longitude field is required when address is present." | Required when address is provided. |
| "address.longitude": "The address.longitude field must be a number." | The value must be a number (decimals allowed). |
| "address.string": "The address.string field is required when address is present." | Required when address is provided. |
| "address.string": "The address.string field must be a string." | The value must be a string. |
| "address.string": "The address.string field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "addressParts": "The address parts field must be an array." | The value must be an array. |
| "addressParts.block": "The address parts.block field must be a string." | The value must be a string. |
| "addressParts.block": "The address parts.block field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.building": "The address parts.building field must be a string." | The value must be a string. |
| "addressParts.building": "The address parts.building field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.building": "The addressParts.building field is required when addressParts is !null." | Required when addressParts is provided. |
| "addressParts.building": "The addressParts.building field is required." | Required field — must be present in the request. |
| "addressParts.building": "The addressParts.building field must be a string." | The value must be a string. |
| "addressParts.building": "The addressParts.building field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.city": "The address parts.city field is required when address parts is present." | Required when addressParts is provided. |
| "addressParts.city": "The address parts.city field must be a string." | The value must be a string. |
| "addressParts.city": "The address parts.city field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.city": "The addressParts.city field is required when addressParts is !null." | Required when addressParts is provided. |
| "addressParts.city": "The addressParts.city field must be a string." | The value must be a string. |
| "addressParts.city": "The addressParts.city field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.flat": "The address parts.flat field must be a string." | The value must be a string. |
| "addressParts.flat": "The address parts.flat field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "addressParts.flat": "The addressParts.flat field must be a string." | The value must be a string. |
| "addressParts.flat": "The addressParts.flat field must not be greater than 10 characters." | The string must be at most 10 characters long. |
| "addressParts.note": "The address parts.note field must be a string." | The value must be a string. |
| "addressParts.note": "The address parts.note field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "addressParts.note": "The addressParts.note field must be a string." | The value must be a string. |
| "addressParts.note": "The addressParts.note field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.postCode": "The address parts.post code field is required when address parts is present." | Required when addressParts is provided. |
| "addressParts.postCode": "The address parts.post code field must be a string." | The value must be a string. |
| "addressParts.postCode": "The address parts.post code field must not be greater than 10 characters." | The string must be at most 10 characters long. |
| "addressParts.postCode": "The addressParts.postCode field is required when addressParts is !null." | Required when addressParts is provided. |
| "addressParts.postCode": "The addressParts.postCode field must be a string." | The value must be a string. |
| "addressParts.postCode": "The addressParts.postCode field must not be greater than 10 characters." | The string must be at most 10 characters long. |
| "addressParts.region": "The address parts.region field is required when address parts is present." | Required when addressParts is provided. |
| "addressParts.region": "The address parts.region field must be a string." | The value must be a string. |
| "addressParts.region": "The address parts.region field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.region": "The addressParts.region field is required when addressParts is !null." | Required when addressParts is provided. |
| "addressParts.region": "The addressParts.region field must be a string." | The value must be a string. |
| "addressParts.region": "The addressParts.region field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.street": "The address parts.street field is required when address parts is present." | Required when addressParts is provided. |
| "addressParts.street": "The address parts.street field must be a string." | The value must be a string. |
| "addressParts.street": "The address parts.street field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "addressParts.street": "The addressParts.street field is required when addressParts is !null." | Required when addressParts is provided. |
| "addressParts.street": "The addressParts.street field must be a string." | The value must be a string. |
| "addressParts.street": "The addressParts.street field must not be greater than 100 characters." | The string must be at most 100 characters long. |
| "afterpayment": "The afterpayment field must be true or false." | The value must be a boolean: true or false. |
| "amount": "The amount field is required." | Required field — must be present in the request. |
| "amount": "The amount field must be a number." | The value must be a number (decimals allowed). |
| "apiKey": "The api key field is required." | Required field — must be present in the request. |
| "apiKey": "The api key field must be a string." | The value must be a string. |
| "apiKey": "The api key field must be at least 32 characters." | The string must be at least 32 characters long. |
| "apiKey": "The api key field must not be greater than 40 characters." | The string must be at most 40 characters long. |
| "appealReason": "The appeal reason field must be 3 digits." | The value must contain exactly 3 digits. |
| "archive": "The archive field must be true or false." | The value must be a boolean: true or false. |
| "attachedDocumentTypeId": "The attached document type id field must be an integer." | The value must be an integer. |
| "attributes": "The attributes field must be an array." | The value must be an array. |
| "attributes.{n}": "The attributes.{n} field has a duplicate value." | The value is duplicated within the array — items must be unique. |
| "attributes.{n}": "The attributes.{n} field must be a string." | The value must be a string. |
| "attributes.{n}": "The selected attributes.{n} is invalid." | The value is not among the allowed values for this field. |
| "barcodes": "The barcodes field is required." | Required field — must be present in the request. |
| "barcodes": "The barcodes field must be an array." | The value must be an array. |
| "barcodes.{n}": "The barcodes.{n} field is required." | Required field — must be present in the request. |
| "blocked": "The blocked field is required." | Required field — must be present in the request. |
| "blocked": "The blocked field must be true or false." | The value must be a boolean: true or false. |
| "bottomLeftLatitude": "The bottom left latitude field is required when bottomLeftLongitude / topRightLatitude / topRightLongitude is present." | Required when any of the following fields is provided: bottomLeftLongitude, topRightLatitude, topRightLongitude. |
| "bottomLeftLongitude": "The bottom left longitude field is required when bottomLeftLatitude / topRightLatitude / topRightLongitude is present." | Required when any of the following fields is provided: bottomLeftLatitude, topRightLatitude, topRightLongitude. |
| "boxId": "The box id field is required." | Required field — must be present in the request. |
| "boxId": "The box id field must be an integer." | The value must be an integer. |
| "canSelectRecipientAsPayer": "The can select recipient as payer field must be true or false." | The value must be a boolean: true or false. |
| "category": "The category field must be a string." | The value must be a string. |
| "category": "The category field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "changeTime": "The change time field is required." | Required field — must be present in the request. |
| "changeTime": "The change time field must be a string." | The value must be a string. |
| "changeTime": "The change time field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "cid": "The cid field is required." | Required field — must be present in the request. |
| "cid": "The cid field must be a string." | The value must be a string. |
| "cid": "The cid field must be a valid UUID." | The value must be a valid UUID. |
| "cids": "The cids field must be an array." | The value must be an array. |
| "cids.{n}": "The cids.{n} field must be a string." | The value must be a string. |
| "claim.accountNumber": "The claim.account number field must be a string." | The value must be a string. |
| "claim.bankAccountNumber": "The claim.bank account number field is required when claim.routing number is present." | Required when claim.routing number is provided. |
| "claim.bankAccountNumber": "The claim.bank account number field must have at least 8 digits." | The value must contain at least 8 digits. |
| "claim.bankAccountNumber": "The claim.bank account number field must not have more than 17 digits." | The value must contain at most 17 digits. |
| "claim.currencyCode": "The claim.currency code field is required." | Required field — must be present in the request. |
| "claim.currencyCode": "The claim.currency code field must be a string." | The value must be a string. |
| "claim.currencyCode": "The selected claim.currency code is invalid." | The value is not among the allowed values for this field. |
| "claim.ibanNumber": "The \"claim.ibanNumber\" does not follow the ISO-13616 format." | The bank account number does not match the IBAN format (ISO 13616 standard). |
| "claim.ibanNumber": "The \"claim.ibanNumber\" is invalid. Checksum validation failed." | The bank account number failed the checksum validation (invalid IBAN). |
| "claim.ibanNumber": "The claim.iban number field must be a string." | The value must be a string. |
| "claim.ibanNumber": "The country code \":country\" is not supported." | The country code in the bank account number (IBAN) is not supported. |
| "claim.mfoBank": "The claim.mfo bank field format is invalid." | The value does not match the expected format of the field. |
| "claim.mfoBank": "The claim.mfo bank field must be a string." | The value must be a string. |
| "claim.routingNumber": "The claim.routing number field is required when claim.bank account number is present." | Required when claim.bank account number is provided. |
| "claim.routingNumber": "The claim.routing number field must be 9 digits." | The value must contain exactly 9 digits. |
| "claim.sum": "The claim.sum field must be a number." | The value must be a number (decimals allowed). |
| "claim.type": "The claim.type field is required." | Required field — must be present in the request. |
| "claim.type": "The claim.type field must be a string." | The value must be a string. |
| "claim.type": "The selected claim.type is invalid." | The value is not among the allowed values for this field. |
| "clientType": "The client type field is required." | Required field — must be present in the request. |
| "clientType": "The client type field must be a string." | The value must be a string. |
| "closed": "The closed field must be true or false." | The value must be a boolean: true or false. |
| "closingDateFrom": "The closing date from field must be a date before or equal to closing date to." | The value must be a date no later than closing date to. |
| "closingDateFrom": "The closing date from field must be a string." | The value must be a string. |
| "closingDateFrom": "The closing date from field must have a value." | The field is present but empty — provide a value. |
| "closingDateTo": "The closing date to field must be a date after or equal to closing date from." | The value must be a date no earlier than closing date from. |
| "closingDateTo": "The closing date to field must be a string." | The value must be a string. |
| "closingDateTo": "The closing date to field must have a value." | The field is present but empty — provide a value. |
| "code": "The code field is required." | Required field — must be present in the request. |
| "codes": "The codes field must be an array." | The value must be an array. |
| "codes.{n}": "The codes.{n} field is required." | Required field — must be present in the request. |
| "codes.{n}": "The codes.{n} field must be a string." | The value must be a string. |
| "codes.{n}": "The codes.{n} field must be at least 3 characters." | The string must be at least 3 characters long. |
| "codes.{n}": "The codes.{n} field must not be greater than 3 characters." | The string must be at most 3 characters long. |
| "companies": "The companies field must be an array." | The value must be an array. |
| "companies.{n}": "The companies.{n} field is required." | Required field — must be present in the request. |
| "companies.{n}": "The companies.{n} field must be a string." | The value must be a string. |
| "companies.{n}": "The companies.{n} field must be at least 2 characters." | The string must be at least 2 characters long. |
| "companies.{n}": "The companies.{n} field must not be greater than 15 characters." | The string must be at most 15 characters long. |
| "companyName": "The company name field must be a string." | The value must be a string. |
| "companyName": "The company name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "companyTin": "Access to the company is forbidden by API key." | Access to the specified company is forbidden for this API key. Check the key permissions for the sender company. |
| "companyTin": "The company tin field is required." | Required field — must be present in the request. |
| "companyTin": "The company tin field must be a string." | The value must be a string. |
| "companyTins": "The company tins field is required when type is legal." | Required when type = legal. |
| "companyTins": "The company tins field must be an array." | The value must be an array. |
| "companyTins.{n}": "The companyTins.{n} field is required." | Required field — must be present in the request. |
| "companyTins.{n}": "The companyTins.{n} field must be a string." | The value must be a string. |
| "compensationReason": "The selected compensationReason is invalid." | The value is not among the allowed values for this field. |
| "complaint": "The complaint field is required." | Required field — must be present in the request. |
| "complaint": "The complaint field must be an array." | The value must be an array. |
| "complaint.description": "The complaint.description field must be a string." | The value must be a string. |
| "complaint.photo": "The complaint.photo field must be an array." | The value must be an array. |
| "complaint.photo.{n}": "The complaint.photo.{n} field must be a string." | The value must be a string. |
| "complaint.type": "The complaint.type field is required." | Required field — must be present in the request. |
| "complaint.type": "The complaint.type field must be a string." | The value must be a string. |
| "complaintPhotos.{n}": "The complaintPhotos.{n} field must be a file of type: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml." | The file must be one of the following types: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml. |
| "complaintPhotos.{n}": "The complaintPhotos.{n} field must not be greater than 4096 kilobytes." | The file size must not exceed 4096 KB. |
| "containsServices": "The contains services field must be true or false." | The value must be a boolean: true or false. |
| "contentType": "The selected content type is invalid." | The value is not among the allowed values for this field. |
| "copies": "The copies field must be a number." | The value must be a number (decimals allowed). |
| "copies": "The copies field must be an integer." | The value must be an integer. |
| "copies": "The copies field must be at least 1." | The value must be at least 1. |
| "copies": "The copies field must not be greater than 10." | The value must be at most 10. |
| "cost": "The cost field format is invalid." | The value does not match the expected format of the field. |
| "cost": "The cost field is required." | Required field — must be present in the request. |
| "count": "The count field is required." | Required field — must be present in the request. |
| "count": "The count field must be an integer." | The value must be an integer. |
| "count": "The count field must be at least 1." | The value must be at least 1. |
| "count": "The count field must not be greater than 100." | The value must be at most 100. |
| "country": "The country field is required." | Required field — must be present in the request. |
| "country": "The country field must be a string." | The value must be a string. |
| "country": "The selected country is invalid." | The value is not among the allowed values for this field. |
| "country-code": "The country-code field is required." | Required field — must be present in the request. |
| "country-code": "The country-code field must be a string." | The value must be a string. |
| "countryCode": "Google search for country is disabled" | Address search is not available for the specified country. |
| "countryCode": "The country code field is required." | Required field — must be present in the request. |
| "countryCode": "The country code field must be 2 characters." | The string must be exactly 2 characters long. |
| "countryCode": "The country code field must be a string." | The value must be a string. |
| "countryCode": "The country code field must be at least 2 characters." | The string must be at least 2 characters long. |
| "countryCode": "The country code field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "countryCode": "The selected country code is invalid." | The value is not among the allowed values for this field. |
| "countryCodes": "The country codes field must be an array." | The value must be an array. |
| "countryCodes.{n}": "The country codes.{n} field must be a string." | The value must be a string. |
| "countryCodes.{n}": "The countryCodes.{n} field is required." | Required field — must be present in the request. |
| "countryCodes.{n}": "The countryCodes.{n} field must be a string." | The value must be a string. |
| "countryCodes.{n}": "The countryCodes.{n} field must be at least 2 characters." | The string must be at least 2 characters long. |
| "countryCodes.{n}": "The countryCodes.{n} field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "createdAtFrom": "The created at from field format is invalid." | The value does not match the expected format of the field. |
| "createdAtFrom": "The created at from field must be a date before created at to." | The value must be a date earlier than created at to. |
| "createdAtFrom": "The created at from field must be a date before or equal to created at to." | The value must be a date no later than created at to. |
| "createdAtFrom": "The created at from field must be a string." | The value must be a string. |
| "createdAtFrom": "The created at from field must be a valid date." | The value must be a valid date. |
| "createdAtFrom": "The created at from field must have a value." | The field is present but empty — provide a value. |
| "createdAtTo": "The created at to field format is invalid." | The value does not match the expected format of the field. |
| "createdAtTo": "The created at to field must be a date after created at from." | The value must be a date later than created at from. |
| "createdAtTo": "The created at to field must be a date after or equal to created at from." | The value must be a date no earlier than created at from. |
| "createdAtTo": "The created at to field must be a string." | The value must be a string. |
| "createdAtTo": "The created at to field must be a valid date." | The value must be a valid date. |
| "createdAtTo": "The created at to field must have a value." | The field is present but empty — provide a value. |
| "createdBy": "The created by field must be a string." | The value must be a string. |
| "createdByUser": "The created by user field must be a string." | The value must be a string. |
| "createdByUser": "The created by user field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "cultureInfo": "The culture info field is required." | Required field — must be present in the request. |
| "cultureInfo": "The culture info field must be a string." | The value must be a string. |
| "cultureInfo": "The culture info field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "currencyCode": "The currency code field is required." | Required field — must be present in the request. |
| "currencyCode": "The currency code field must be a string." | The value must be a string. |
| "currency_code": "The currency code field is required." | Required field — must be present in the request. |
| "currency_code": "The selected currency code is invalid." | The value is not among the allowed values for this field. |
| "cursor": "The cursor field must be a string." | The value must be a string. |
| "customer": "The customer field is required." | Required field — must be present in the request. |
| "customer": "The customer field must be a string." | The value must be a string. |
| "customer": "The selected customer is invalid." | The value is not among the allowed values for this field. |
| "customerInput": "The customer input field is required." | Required field — must be present in the request. |
| "customerServiceAvailable": "The customer service available field must be true or false." | The value must be a boolean: true or false. |
| "customerTINPhotos": "The customer t i n photos field must be an array." | The value must be an array. |
| "customerTINPhotos.{n}": "The customerTINPhotos.{n} field must be a file of type: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml." | The file must be one of the following types: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml. |
| "customerTINPhotos.{n}": "The customerTINPhotos.{n} field must be a string." | The value must be a string. |
| "customerTINPhotos.{n}": "The customerTINPhotos.{n} field must not be greater than 4096 kilobytes." | The file size must not exceed 4096 KB. |
| "customerTin": "The customer tin field must be a string." | The value must be a string. |
| "customerType": "The selected customer type is invalid." | The value is not among the allowed values for this field. |
| "date": "The date field is required." | Required field — must be present in the request. |
| "date": "The date field must match the format Y-m-d\TH:i:s.u\Z." | The value must match the ISO 8601 date-time format in UTC, e.g. 2026-07-21T12:00:00.000Z. |
| "deleted": "The deleted field must be true or false." | The value must be a boolean: true or false. |
| "deletionMark": "The deletion mark field must be true or false." | The value must be a boolean: true or false. |
| "deletionMark": "The deletion mark field must have a value." | The field is present but empty — provide a value. |
| "deliveryPartner": "The delivery partner field must be a string." | The value must be a string. |
| "deliveryPartner": "The selected delivery partner is invalid." | The value is not among the allowed values for this field. |
| "deliveryType": "The delivery type field must be a string." | The value must be a string. |
| "deliveryType": "The selected delivery type is invalid." | The value is not among the allowed values for this field. |
| "deliveryTypes": "The delivery types field must be an array." | The value must be an array. |
| "deliveryTypes": "The selected delivery types is invalid." | The value is not among the allowed values for this field. |
| "description": "The description field must be a string." | The value must be a string. |
| "description": "The description field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "divisionCategories": "The division categories field must be an array." | The value must be an array. |
| "divisionCategories.{n}": "The divisionCategories.{n} field must be a string." | The value must be a string. |
| "divisionCategoryIds": "The division category ids field must be an array." | The value must be an array. |
| "divisionCategoryIds.{n}": "The divisionCategoryIds.{n} field must be an integer." | The value must be an integer. |
| "divisionCategoryIds.{n}": "The divisionCategoryIds.{n} field must be greater than 0." | The value must be greater than 0. |
| "divisionId": "The division id field must be an integer." | The value must be an integer. |
| "divisionIds": "The division ids field must be an array." | The value must be an array. |
| "divisionIds.{n}": "The division ids.{n} field must be a string." | The value must be a string. |
| "docNumber": "The doc number field is required." | Required field — must be present in the request. |
| "docNumber": "The doc number field must be a string." | The value must be a string. |
| "docNumber": "The doc number field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "documentType": "The document type field must be a string." | The value must be a string. |
| "documentType": "The selected document type is invalid." | The value is not among the allowed values for this field. |
| "email": "The email field must be a valid email address." | The value must be a valid email address. |
| "email": "The email field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "errorState": "The error state field must be a string." | The value must be a string. |
| "errorState": "The error state field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "eventTypes": "The event types field must be an array." | The value must be an array. |
| "eventTypes.{n}": "The eventTypes.{n} field is required." | Required field — must be present in the request. |
| "eventTypes.{n}": "The eventTypes.{n} field must be a string." | The value must be a string. |
| "export": "The export field must be true or false." | The value must be a boolean: true or false. |
| "expressDecision": "The express decision field must be a string." | The value must be a string. |
| "expressDecision": "The selected expressDecision is invalid." | The value is not among the allowed values for this field. |
| "extended": "The extended field must be true or false." | The value must be a boolean: true or false. |
| "externalIds": "The external ids field must be an array." | The value must be an array. |
| "externalIds.{n}": "The externalIds.{n} field is required." | Required field — must be present in the request. |
| "externalIds.{n}": "The externalIds.{n} field must be a string." | The value must be a string. |
| "externalIds.{n}": "The externalIds.{n} field must be an integer." | The value must be an integer. |
| "externalIds.{n}": "The externalIds.{n} field must be greater than 0." | The value must be greater than 0. |
| "file": "The file field is required." | Required field — must be present in the request. |
| "file": "The file field must be a string." | The value must be a string. |
| "fileContentType": "The file content type field must be a string." | The value must be a string. |
| "fileId": "The file id field is required." | Required field — must be present in the request. |
| "fileId": "The file id field must be a string." | The value must be a string. |
| "fileName": "The file name field must be a string." | The value must be a string. |
| "files": "Missing file data" | Mandatory file data is missing (type or content). |
| "files": "Too many files" | The allowed number of files in the request is exceeded. |
| "files.{n}.file": "File is too large to upload" | The file size exceeds the allowed limit. |
| "files.{n}.metadata.typeCode": "Missing file data" | Mandatory file data is missing (type or content). |
| "files.{n}.metadata.typeId": "Missing file data" | Mandatory file data is missing (type or content). |
| "firstName": "The first name field is required." | Required field — must be present in the request. |
| "firstName": "The first name field must be a string." | The value must be a string. |
| "flowType": "The flow type field is required." | Required field — must be present in the request. |
| "flowType": "The flow type field must be a string." | The value must be a string. |
| "fullList": "The full list field must be true or false." | The value must be a boolean: true or false. |
| "fullName": "The full name field is required." | Required field — must be present in the request. |
| "fullName": "The full name field must be a string." | The value must be a string. |
| "fullName": "The full name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "fuzzy": "The fuzzy field must be true or false." | The value must be a boolean: true or false. |
| "hasArrival": "The has arrival field must be true or false." | The value must be a boolean: true or false. |
| "hasStorage": "The has storage field must be true or false." | The value must be a boolean: true or false. |
| "iBans": "The i bans field must be an array." | The value must be an array. |
| "iBans.{n}": "The iBans.{n} field is required." | Required field — must be present in the request. |
| "iBans.{n}": "The iBans.{n} field must be a string." | The value must be a string. |
| "id": "The id field is required." | Required field — must be present in the request. |
| "id": "The id field must be a string." | The value must be a string. |
| "id": "The id field must be a valid UUID." | The value must be a valid UUID. |
| "id": "The id field must be an integer." | The value must be an integer. |
| "id": "The id field must be at least 1." | The value must be at least 1. |
| "id": "The id must be a valid UUID or integer." | The identifier must be a valid UUID or an integer. |
| "identificationSource": "The identification source field is required." | Required field — must be present in the request. |
| "identificationSource": "The identification source field must be an integer." | The value must be an integer. |
| "ids": "The ids field is required when none of numbers / trackingDateFrom / trackingDateTo are present." | Required when none of the following fields are provided: numbers, trackingDateFrom, trackingDateTo. |
| "ids": "The ids field is required when numbers is not present." | Required when numbers is not provided. |
| "ids": "The ids field must be an array." | The value must be an array. |
| "ids": "The ids field must have a value." | The field is present but empty — provide a value. |
| "ids": "The ids field must not have more than 100 items." | The array must contain at most 100 items. |
| "ids": "The ids field must not have more than 200 items." | The array must contain at most 200 items. |
| "ids.{n}": "The ids.{n} field is required." | Required field — must be present in the request. |
| "ids.{n}": "The ids.{n} field must be a string." | The value must be a string. |
| "ids.{n}": "The ids.{n} field must be an integer." | The value must be an integer. |
| "ids.{n}": "The ids.{n} field must be greater than 0." | The value must be greater than 0. |
| "import": "The import field must be true or false." | The value must be a boolean: true or false. |
| "inRegistry": "The in registry field must be true or false." | The value must be a boolean: true or false. |
| "international": "The international field must be true or false." | The value must be a boolean: true or false. |
| "invoice": "The invoice field must be an array." | The value must be an array. |
| "invoice.clientInvoice": "The invoice.client invoice field must be an integer." | The value must be an integer. |
| "invoice.clientInvoice": "The selected invoice.client invoice is invalid." | The value is not among the allowed values for this field. |
| "invoice.cost": "The invoice.cost field format is invalid." | The value does not match the expected format of the field. |
| "invoice.cost": "The invoice.cost field is required when invoice.currency is present." | Required when invoice.currency is provided. |
| "invoice.cost": "The invoice.cost field is required." | Required field — must be present in the request. |
| "invoice.cost": "The invoice.cost field must be a number." | The value must be a number (decimals allowed). |
| "invoice.cost": "The invoice.cost field must be at least 0." | The value must be at least 0. |
| "invoice.cost": "The invoice.cost field must be greater than or equal to 0." | The value must be at least 0. |
| "invoice.cost": "The invoice.cost field must be less than or equal to 9999999999.99." | The value must be at most 9999999999.99. |
| "invoice.cost": "The invoice.cost field must not be greater than 999999999.99." | The value must be at most 999999999.99. |
| "invoice.currency": "The invoice.currency field format is invalid." | The value does not match the expected format of the field. |
| "invoice.currency": "The invoice.currency field is required when invoice.cost is present." | Required when invoice.cost is provided. |
| "invoice.currency": "The invoice.currency field is required." | Required field — must be present in the request. |
| "invoice.currency": "The invoice.currency field must be a string." | The value must be a string. |
| "invoice.currency": "The selected invoice.currency is invalid." | The value is not among the allowed values for this field. |
| "invoice.customerCreatedAt": "The invoice.customer created at field is required." | Required field — must be present in the request. |
| "invoice.customerCreatedAt": "The invoice.customer created at field must be a string." | The value must be a string. |
| "invoice.customerCreatedAt": "The invoice.customer created at field must match the format Y-m-d." | The value must match the date format YYYY-MM-DD, e.g. 2026-07-21. |
| "invoice.customerCreatedAt": "The invoice.customer created at field must match the format Y-m-d\TH:i:s.u\Z." | The value must match the ISO 8601 date-time format in UTC, e.g. 2026-07-21T12:00:00.000Z. |
| "invoice.customerNumber": "Client invoice number required" | Required field — specify the client invoice number. |
| "invoice.customerNumber": "The invoice.customer number field is required." | Required field — must be present in the request. |
| "invoice.customerNumber": "The invoice.customer number field must be a string." | The value must be a string. |
| "invoice.customerNumber": "The invoice.customer number field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "invoice.customerNumber": "The invoice.customer number field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "invoice.exportReason": "The invoice.export reason field is required." | Required field — must be present in the request. |
| "invoice.exportReason": "The invoice.export reason field must be a string." | The value must be a string. |
| "invoice.exportReason": "The selected invoice.export reason is invalid." | The value is not among the allowed values for this field. |
| "invoice.incoterm": "The invoice.incoterm field is required." | Required field — must be present in the request. |
| "invoice.incoterm": "The invoice.incoterm field must be a string." | The value must be a string. |
| "invoice.incoterm": "The selected invoice.incoterm is invalid." | The value is not among the allowed values for this field. |
| "invoice.invoiceFile": "Client invoice file required" | Required field — attach the client invoice file. |
| "invoice.invoiceFile": "The invoice.invoice file field must be an array." | The value must be an array. |
| "invoice.invoiceFile.base64Content": "The invoice.invoice file.base64 content field must be a string." | The value must be a string. |
| "invoice.invoiceFile.base64Content": "file is required" | Required field — provide the file content (base64). |
| "invoice.invoiceFile.filename": "The invoice.invoice file.filename field must be a string." | The value must be a string. |
| "invoice.invoiceFile.filename": "filename is required" | Required field — specify the file name. |
| "invoice.invoiceSign": "Client invoice signature required" | Required field — specify the client invoice signature. |
| "invoice.invoiceSign": "The invoice.invoice sign field must be an integer." | The value must be an integer. |
| "invoice.invoiceType": "The invoice.invoice type field is required." | Required field — must be present in the request. |
| "invoice.invoiceType": "The invoice.invoice type field must be a string." | The value must be a string. |
| "invoice.invoiceType": "The selected invoice.invoice type is invalid." | The value is not among the allowed values for this field. |
| "invoice.iossCode": "IOSSNumber is incorrect" | Invalid IOSS number. |
| "invoice.iossCode": "The invoice.ioss code field must be a string." | The value must be a string. |
| "invoice.iossCode": "The invoice.ioss code field must be at least 8 characters." | The string must be at least 8 characters long. |
| "invoice.iossCode": "The invoice.ioss code field must not be greater than 12 characters." | The string must be at most 12 characters long. |
| "invoice.items": "Invoice item currencies must match." | All invoice items must use the same currency. |
| "invoice.items": "The invoice.items field is required." | Required field — must be present in the request. |
| "invoice.items": "The invoice.items field must be an array." | The value must be an array. |
| "invoice.items": "The invoice.items field must have at least 1 items." | The array must contain at least 1 item(s). |
| "invoice.items.{n}.actualWeight": "The invoice.items.{n}.actual weight field must be a number." | The value must be a number (decimals allowed). |
| "invoice.items.{n}.actualWeight": "The invoice.items.{n}.actual weight field must be less than or equal to 2147483647." | The value must be at most 2147483647. |
| "invoice.items.{n}.amount": "The invoice.items.{n}.amount field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.amount": "The invoice.items.{n}.amount field must be an integer." | The value must be an integer. |
| "invoice.items.{n}.amount": "The invoice.items.{n}.amount field must be at least 1." | The value must be at least 1. |
| "invoice.items.{n}.amount": "invoice.items.{n}.amount must be a positive integer" | The value must be a positive integer. |
| "invoice.items.{n}.cost": "The invoice.items.{n}.cost field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.cost": "The invoice.items.{n}.cost field must be a number." | The value must be a number (decimals allowed). |
| "invoice.items.{n}.cost": "The invoice.items.{n}.cost field must be greater than 0." | The value must be greater than 0. |
| "invoice.items.{n}.currency": "The invoice.items.{n}.currency field format is invalid." | The value does not match the expected format of the field. |
| "invoice.items.{n}.currency": "The invoice.items.{n}.currency field must be a string." | The value must be a string. |
| "invoice.items.{n}.currency": "The selected invoice.items.{n}.currency is invalid." | The value is not among the allowed values for this field. |
| "invoice.items.{n}.hsCode": "HsCode must contain exactly 10 digits" | The UKT ZED (HS) code must contain exactly 10 digits. |
| "invoice.items.{n}.hsCode": "The invoice.items.{n}.hs code field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.hsCode": "The invoice.items.{n}.hs code field must be a string." | The value must be a string. |
| "invoice.items.{n}.hsCode": "The invoice.items.{n}.hs code field must not be greater than 10 characters." | The string must be at most 10 characters long. |
| "invoice.items.{n}.hsCodeClearance": "Invoice.items.{n}.hsCodeClearance must contain exactly 8 digits" | The customs-clearance UKT ZED (HS) code must contain exactly 8 digits. |
| "invoice.items.{n}.hsCodeClearance": "The invoice.items.{n}.hs code clearance field must be a string." | The value must be a string. |
| "invoice.items.{n}.hsCodeDeclaration": "Invoice.items.{n}.hsCodeDeclaration must contain exactly 8 digits" | The declaration UKT ZED (HS) code must contain exactly 8 digits. |
| "invoice.items.{n}.hsCodeDeclaration": "The invoice.items.{n}.hs code declaration field must be a string." | The value must be a string. |
| "invoice.items.{n}.material": "The invoice.items.{n}.material field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.material": "The invoice.items.{n}.material field must be a string." | The value must be a string. |
| "invoice.items.{n}.material": "The invoice.items.{n}.material field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "invoice.items.{n}.measurementCode": "The invoice.items.{n}.measurement code field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.measurementCode": "The invoice.items.{n}.measurement code field must be a string." | The value must be a string. |
| "invoice.items.{n}.name": "The invoice.items.{n}.name field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.name": "The invoice.items.{n}.name field must be a string." | The value must be a string. |
| "invoice.items.{n}.name": "The invoice.items.{n}.name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "invoice.items.{n}.nameEng": "The invoice.items.{n}.name eng field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.nameEng": "The invoice.items.{n}.name eng field must be a string." | The value must be a string. |
| "invoice.items.{n}.nameEng": "The invoice.items.{n}.name eng field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "invoice.items.{n}.packingType": "The invoice.items.{n}.packing type field must be a string." | The value must be a string. |
| "invoice.items.{n}.packingType": "The invoice.items.{n}.packing type field must not be greater than 30 characters." | The string must be at most 30 characters long. |
| "invoice.items.{n}.producerAndModel": "The invoice.items.{n}.producer and model field must be a string." | The value must be a string. |
| "invoice.items.{n}.rowNumber": "invoice.items.{n}.rowNumber must be a positive integer" | The value must be a positive integer. |
| "invoice.items.{n}.weight": "The invoice.items.{n}.weight field is required." | Required field — must be present in the request. |
| "invoice.items.{n}.weight": "The invoice.items.{n}.weight field must be a number." | The value must be a number (decimals allowed). |
| "invoice.items.{n}.weight": "The invoice.items.{n}.weight field must be greater than 0." | The value must be greater than 0. |
| "invoice.payerChargeCustoms": "The invoice.payer charge customs field must be a string." | The value must be a string. |
| "invoice.payerChargeCustoms": "The selected invoice.payer charge customs is invalid." | The value is not among the allowed values for this field. |
| "invoice.payerFeesCustoms": "The invoice.payer fees customs field is required." | Required field — must be present in the request. |
| "invoice.payerFeesCustoms": "The invoice.payer fees customs field must be a string." | The value must be a string. |
| "invoice.payerFeesCustoms": "The selected invoice.payer fees customs is invalid." | The value is not among the allowed values for this field. |
| "invoice.type": "The invoice.type field must be a string." | The value must be a string. |
| "isActive": "The is active field is required." | Required field — must be present in the request. |
| "isActive": "The is active field must be true or false." | The value must be a boolean: true or false. |
| "isEURegistry": "The is e u registry field must be true or false." | The value must be a boolean: true or false. |
| "isThirdPartyPayerContract": "The is third party payer contract field must be true or false." | The value must be a boolean: true or false. |
| "keyword": "The keyword field is required." | Required field — must be present in the request. |
| "keyword": "The keyword field must be a string." | The value must be a string. |
| "keyword": "The keyword field must be at least 3 characters." | The string must be at least 3 characters long. |
| "keyword": "The keyword field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "lang": "The lang field must be a string." | The value must be a string. |
| "lang": "The lang field must be at least 2 characters." | The string must be at least 2 characters long. |
| "lang": "The lang field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "lastName": "The last name field is required." | Required field — must be present in the request. |
| "lastName": "The last name field must be a string." | The value must be a string. |
| "latitude": "The latitude field is required when longitude is present." | Required when longitude is provided. |
| "latitude": "The latitude field must be a number." | The value must be a number (decimals allowed). |
| "legalAddress": "The legal address field must be a string." | The value must be a string. |
| "limit": "The limit field must be an integer." | The value must be an integer. |
| "limit": "The limit field must be at least 1." | The value must be at least 1. |
| "limit": "The limit field must have a value." | The field is present but empty — provide a value. |
| "limit": "The limit field must not be greater than 100." | The value must be at most 100. |
| "limit": "The limit field must not be greater than 101." | The value must be at most 101. |
| "locale": "The locale field must be a string." | The value must be a string. |
| "locale": "The locale field must be at least 2 characters." | The string must be at least 2 characters long. |
| "locale": "The locale field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "lockVersion": "The lock version field is required." | Required field — must be present in the request. |
| "lockVersion": "The lock version field must be an integer." | The value must be an integer. |
| "lockVersion": "The lock version field must be at least 1." | The value must be at least 1. |
| "longitude": "The longitude field is required when latitude is present." | Required when latitude is provided. |
| "longitude": "The longitude field must be a number." | The value must be a number (decimals allowed). |
| "main": "The main field is required." | Required field — must be present in the request. |
| "main": "The main field must be true or false." | The value must be a boolean: true or false. |
| "mainPayerType": "The main payer type field must be an array." | The value must be an array. |
| "mainPayerType.{n}": "The main payer type.{n} field must be a string." | The value must be a string. |
| "mainPayerType.{n}": "The selected main payer type.{n} is invalid." | The value is not among the allowed values for this field. |
| "maxDeclaredCostPlace": "The max declared cost place field must be a number." | The value must be a number (decimals allowed). |
| "maxDeclaredCostPlace": "The max declared cost place field must be at least 1." | The value must be at least 1. |
| "maxHeightPlaceRecipient": "The max height place recipient field must be an integer." | The value must be an integer. |
| "maxHeightPlaceRecipient": "The max height place recipient field must be at least 1." | The value must be at least 1. |
| "maxHeightPlaceSender": "The max height place sender field must be an integer." | The value must be an integer. |
| "maxHeightPlaceSender": "The max height place sender field must be at least 1." | The value must be at least 1. |
| "maxLengthPlaceRecipient": "The max length place recipient field must be an integer." | The value must be an integer. |
| "maxLengthPlaceRecipient": "The max length place recipient field must be at least 1." | The value must be at least 1. |
| "maxLengthPlaceSender": "The max length place sender field must be an integer." | The value must be an integer. |
| "maxLengthPlaceSender": "The max length place sender field must be at least 1." | The value must be at least 1. |
| "maxWeightPlaceRecipient": "The max weight place recipient field must be an integer." | The value must be an integer. |
| "maxWeightPlaceRecipient": "The max weight place recipient field must be at least 1." | The value must be at least 1. |
| "maxWeightPlaceSender": "The max weight place sender field must be an integer." | The value must be an integer. |
| "maxWeightPlaceSender": "The max weight place sender field must be at least 1." | The value must be at least 1. |
| "maxWidthPlaceRecipient": "The max width place recipient field must be an integer." | The value must be an integer. |
| "maxWidthPlaceRecipient": "The max width place recipient field must be at least 1." | The value must be at least 1. |
| "maxWidthPlaceSender": "The max width place sender field must be an integer." | The value must be an integer. |
| "maxWidthPlaceSender": "The max width place sender field must be at least 1." | The value must be at least 1. |
| "middleName": "The middle name field must be a string." | The value must be a string. |
| "moneyTransfer": "The money transfer field must be true or false." | The value must be a boolean: true or false. |
| "name": "The name field is required." | Required field — must be present in the request. |
| "name": "The name field must be a string." | The value must be a string. |
| "name": "The name field must be at least 1 characters." | The string must be at least 1 characters long. |
| "name": "The name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "needPay": "The need pay field must be true or false." | The value must be a boolean: true or false. |
| "notExistPickup": "The not exist pickup field must be true or false." | The value must be a boolean: true or false. |
| "notOwnerDocumentTypes": "The not owner document types field must be true or false." | The value must be a boolean: true or false. |
| "note": "The note field must be a string." | The value must be a string. |
| "note": "The note field must not be greater than 1000 characters." | The string must be at most 1000 characters long. |
| "note": "The note field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "number": "The number field is required." | Required field — must be present in the request. |
| "number": "The number field must be a string." | The value must be a string. |
| "number": "The number field must be at least 1 character." | The string must be at least 1 characters long. |
| "number": "The number field must be at least 2 characters." | The string must be at least 2 characters long. |
| "number": "The number field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "number": "The number field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "numbers": "The numbers field is required when ids is not present." | Required when ids is not provided. |
| "numbers": "The numbers field is required when none of ids / trackingDateFrom / trackingDateTo are present." | Required when none of the following fields are provided: ids, trackingDateFrom, trackingDateTo. |
| "numbers": "The numbers field is required." | Required field — must be present in the request. |
| "numbers": "The numbers field must be an array." | The value must be an array. |
| "numbers": "The numbers field must have a value." | The field is present but empty — provide a value. |
| "numbers": "The numbers field must have at least 1 items." | The array must contain at least 1 item(s). |
| "numbers": "The numbers field must not have more than 100 items." | The array must contain at most 100 items. |
| "numbers": "The numbers field must not have more than 200 items." | The array must contain at most 200 items. |
| "numbers.{n}": "The numbers.{n} field is required." | Required field — must be present in the request. |
| "numbers.{n}": "The numbers.{n} field must be a string." | The value must be a string. |
| "onlySelfNumber": "The only self number field must be true or false." | The value must be a boolean: true or false. |
| "organizationName": "The organization name field must be a string." | The value must be a string. |
| "page": "The page field must be an integer." | The value must be an integer. |
| "page": "The page field must be at least 1." | The value must be at least 1. |
| "page": "The page field must have a value." | The field is present but empty — provide a value. |
| "parcelNumber": "The parcel number field is required." | Required field — must be present in the request. |
| "parcels": "The parcels field is required." | Required field — must be present in the request. |
| "parcels": "The parcels field must be an array." | The value must be an array. |
| "parcels.{n}.actualWeight": "The parcels.{n}.actual weight field is required." | Required field — must be present in the request. |
| "parcels.{n}.actualWeight": "The parcels.{n}.actual weight field must be a number." | The value must be a number (decimals allowed). |
| "parcels.{n}.actualWeight": "The parcels.{n}.actual weight field must be an integer." | The value must be an integer. |
| "parcels.{n}.actualWeight": "The parcels.{n}.actual weight field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.actualWeight": "The parcels.{n}.actual weight field must be less than or equal to 2147483647." | The value must be at most 2147483647. |
| "parcels.{n}.cargoCategory": "The parcels.{n}.cargo category field is required." | Required field — must be present in the request. |
| "parcels.{n}.cargoCategory": "The parcels.{n}.cargo category field must be a string." | The value must be a string. |
| "parcels.{n}.cargoCategory": "The selected parcels.{n}.cargo category is invalid." | The value is not among the allowed values for this field. |
| "parcels.{n}.clientParcel": "The parcels.{n}.client parcel field must be an array." | The value must be an array. |
| "parcels.{n}.clientParcel.number": "The parcels.{n}.client parcel.number field must be a string." | The value must be a string. |
| "parcels.{n}.height": "The parcels.{n}.height field is required." | Required field — must be present in the request. |
| "parcels.{n}.height": "The parcels.{n}.height field must be an integer." | The value must be an integer. |
| "parcels.{n}.height": "The parcels.{n}.height field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.height": "The parcels.{n}.height field must be less than or equal to 32767." | The value must be at most 32767. |
| "parcels.{n}.insuranceCost": "The parcels.{n}.insurance cost field is required." | Required field — must be present in the request. |
| "parcels.{n}.insuranceCost": "The parcels.{n}.insurance cost field must be a number." | The value must be a number (decimals allowed). |
| "parcels.{n}.insuranceCost": "The parcels.{n}.insurance cost field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.insuranceCost": "parcels.*.insuranceCost is required." | Required field — specify the parcel insurance value. |
| "parcels.{n}.insuranceCost": "parcels.*.insuranceCost should be a valid number." | The parcel insurance value must be a valid number. |
| "parcels.{n}.length": "The parcels.{n}.length field is required." | Required field — must be present in the request. |
| "parcels.{n}.length": "The parcels.{n}.length field must be an integer." | The value must be an integer. |
| "parcels.{n}.length": "The parcels.{n}.length field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.length": "The parcels.{n}.length field must be less than or equal to 32767." | The value must be at most 32767. |
| "parcels.{n}.number": "The parcels.{n}.number field must be a string." | The value must be a string. |
| "parcels.{n}.parcelDescription": "The parcels.{n}.parcel description field is required." | Required field — must be present in the request. |
| "parcels.{n}.parcelDescription": "The parcels.{n}.parcel description field must be a string." | The value must be a string. |
| "parcels.{n}.parcelDescription": "The parcels.{n}.parcel description field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "parcels.{n}.parcelDescription": "The parcels.{n}.parcel description field must not be greater than 3000 characters." | The string must be at most 3000 characters long. |
| "parcels.{n}.rowNumber": "The parcels.{n}.row number field has a duplicate value." | The value is duplicated within the array — items must be unique. |
| "parcels.{n}.rowNumber": "The parcels.{n}.row number field is required." | Required field — must be present in the request. |
| "parcels.{n}.rowNumber": "The parcels.{n}.row number field must be an integer." | The value must be an integer. |
| "parcels.{n}.rowNumber": "The parcels.{n}.row number field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.rowNumber": "The selected parcels.{n}.row number is invalid." | The value is not among the allowed values for this field. |
| "parcels.{n}.width": "The parcels.{n}.width field is required." | Required field — must be present in the request. |
| "parcels.{n}.width": "The parcels.{n}.width field must be an integer." | The value must be an integer. |
| "parcels.{n}.width": "The parcels.{n}.width field must be greater than 0." | The value must be greater than 0. |
| "parcels.{n}.width": "The parcels.{n}.width field must be less than or equal to 32767." | The value must be at most 32767. |
| "parcelsCount": "The parcels count field is required." | Required field — must be present in the request. |
| "parcelsCount": "The parcels count field must be an integer." | The value must be an integer. |
| "parcelsCount": "The parcels count field must be greater than 0." | The value must be greater than 0. |
| "payerContractNumber": "The payer contract number field is required when payer type is ThirdPerson." | Required when payerType = ThirdPerson. |
| "payerContractNumber": "The payer contract number field is required." | Required field — must be present in the request. |
| "payerContractNumber": "The payer contract number field must be a string." | The value must be a string. |
| "payerContractNumber": "The payer contract number field must be at least 2 characters." | The string must be at least 2 characters long. |
| "payerContractNumber": "The payer contract number field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "payerType": "Service 'Receiver pays' is not available for this destination country." | The 'Receiver pays' service is not available for the destination country. |
| "payerType": "The payer type field is required." | Required field — must be present in the request. |
| "payerType": "The payer type field must be a string." | The value must be a string. |
| "payerType": "The payer type field must be an array." | The value must be an array. |
| "payerType": "The selected payer type is invalid." | The value is not among the allowed values for this field. |
| "payerType.{n}": "The payer type.{n} field must be a string." | The value must be a string. |
| "payerType.{n}": "The selected payer type.{n} is invalid." | The value is not among the allowed values for this field. |
| "paymentStatus": "The payment status field is required." | Required field — must be present in the request. |
| "paymentStatus": "The payment status field must be an array." | The value must be an array. |
| "paymentStatus": "The payment status field must be true or false." | The value must be a boolean: true or false. |
| "paymentStatus.{n}": "The payment status.{n} field must be a string." | The value must be a string. |
| "paymentStatus.{n}": "The selected payment status.{n} is invalid." | The value is not among the allowed values for this field. |
| "phone": "The phone field is required." | Required field — must be present in the request. |
| "phone": "The phone field must be a string." | The value must be a string. |
| "pickedTimeFrom": "The picked time from field must be a date before picked time to." | The value must be a date earlier than picked time to. |
| "pickedTimeFrom": "The picked time from field must be a string." | The value must be a string. |
| "pickedTimeFrom": "The picked time from field must be a valid date." | The value must be a valid date. |
| "pickedTimeOnlyNull": "The picked time only null field must be true or false." | The value must be a boolean: true or false. |
| "pickedTimeTo": "The picked time to field must be a date after picked time from." | The value must be a date later than picked time from. |
| "pickedTimeTo": "The picked time to field must be a string." | The value must be a string. |
| "pickedTimeTo": "The picked time to field must be a valid date." | The value must be a valid date. |
| "pickupId": "The pickup id field must be an integer." | The value must be an integer. |
| "pickupShipmentStatuses": "The pickup shipment statuses field must be an array." | The value must be an array. |
| "pickupShipmentStatuses.{n}": "The pickup shipment statuses.{n} field must be a string." | The value must be a string. |
| "pickupsShipmentIds": "The pickups shipment ids field must be an array." | The value must be an array. |
| "pickupsShipmentIds.{n}": "The pickups shipment ids.{n} field must be a string." | The value must be a string. |
| "postCodes": "The post codes field must be an array." | The value must be an array. |
| "postCodes.{n}": "The postCodes.{n} field is required." | Required field — must be present in the request. |
| "postCodes.{n}": "The postCodes.{n} field must be a string." | The value must be a string. |
| "printSizeType": "The print size type field is required." | Required field — must be present in the request. |
| "printSizeType": "The selected print size type is invalid." | The value is not among the allowed values for this field. |
| "printed": "The printed field must be true or false." | The value must be a boolean: true or false. |
| "prohibitedIssuance": "The prohibited issuance field must be true or false." | The value must be a boolean: true or false. |
| "prohibitedSending": "The prohibited sending field must be true or false." | The value must be a boolean: true or false. |
| "promoCode": "The promo code field must be a string." | The value must be a string. |
| "promoCode": "The promo code field must be at least 3 characters." | The string must be at least 3 characters long. |
| "recipient": "The recipient field is required." | Required field — must be present in the request. |
| "recipient": "The recipient field must be an array." | The value must be an array. |
| "recipient.address": "The recipient.address field is required when none of recipient.division id / recipient.address parts / recipient.division number are present." | Required when none of the following fields are provided: recipient.divisionId, recipient.addressParts, recipient.divisionNumber. |
| "recipient.addressParts": "The recipient.address parts field is required when none of recipient.division id / recipient.address / recipient.division number are present." | Required when none of the following fields are provided: recipient.divisionId, recipient.address, recipient.divisionNumber. |
| "recipient.addressParts": "The recipient.address parts field is required when recipient.division id is not present." | Required when recipient.divisionId is not provided. |
| "recipient.addressParts": "The recipient.address parts field must be an array." | The value must be an array. |
| "recipient.addressParts.addressLine1": "The recipient.address parts.address line1 field is required when none of recipient.address parts.street / recipient.address parts.building / recipient.division id / recipient.address / recipient.division number are present." | Required when none of the following fields are provided: recipient.addressParts.street, recipient.addressParts.building, recipient.divisionId, recipient.address, recipient.divisionNumber. |
| "recipient.addressParts.addressLine2": "The recipient.address parts.address line2 field must be a string." | The value must be a string. |
| "recipient.addressParts.addressLine3": "The recipient.address parts.address line3 field must be a string." | The value must be a string. |
| "recipient.addressParts.building": "The recipient.address parts.building field is required when recipient.address parts is present." | Required when recipient.addressParts is provided. |
| "recipient.addressParts.building": "The recipient.address parts.building field is required." | Required field — must be present in the request. |
| "recipient.addressParts.building": "The recipient.address parts.building field must be a string." | The value must be a string. |
| "recipient.addressParts.building": "The recipient.address parts.building field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "recipient.addressParts.city": "The recipient.address parts.city field is required when recipient.address parts is present." | Required when recipient.addressParts is provided. |
| "recipient.addressParts.city": "The recipient.address parts.city field is required when recipient.address parts.address line1 is present." | Required when recipient.addressParts.addressLine1 is provided. |
| "recipient.addressParts.city": "The recipient.address parts.city field must be a string." | The value must be a string. |
| "recipient.addressParts.city": "The recipient.address parts.city field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.addressParts.postCode": "The recipient.address parts.post code field is required when recipient.address parts is present." | Required when recipient.addressParts is provided. |
| "recipient.addressParts.postCode": "The recipient.address parts.post code field is required when recipient.address parts.address line1 is present." | Required when recipient.addressParts.addressLine1 is provided. |
| "recipient.addressParts.postCode": "The recipient.address parts.post code field must be a string." | The value must be a string. |
| "recipient.addressParts.postCode": "The recipient.address parts.post code field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "recipient.addressParts.region": "The recipient.address parts.region field is required when recipient.address parts is present." | Required when recipient.addressParts is provided. |
| "recipient.addressParts.region": "The recipient.address parts.region field must be a string." | The value must be a string. |
| "recipient.addressParts.region": "The recipient.address parts.region field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.addressParts.street": "The recipient.address parts.street field is required when none of recipient.address parts.address line1 / recipient.division id / recipient.address / recipient.division number are present." | Required when none of the following fields are provided: recipient.addressParts.addressLine1, recipient.divisionId, recipient.address, recipient.divisionNumber. |
| "recipient.addressParts.street": "The recipient.address parts.street field is required when recipient.address parts is present." | Required when recipient.addressParts is provided. |
| "recipient.addressParts.street": "The recipient.address parts.street field is required when recipient.address parts.building is present." | Required when recipient.addressParts.building is provided. |
| "recipient.addressParts.street": "The recipient.address parts.street field must be a string." | The value must be a string. |
| "recipient.addressParts.street": "The recipient.address parts.street field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.companyName": "The recipient.company name field must be a string." | The value must be a string. |
| "recipient.companyName": "The recipient.company name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.companyTin": "The recipient.company tin field must be a string." | The value must be a string. |
| "recipient.companyTin": "The recipient.company tin field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "recipient.countryCode": "The recipient.country code field is required when recipient.address parts.address line1 is present." | Required when recipient.addressParts.addressLine1 is provided. |
| "recipient.countryCode": "The recipient.country code field is required." | Required field — must be present in the request. |
| "recipient.countryCode": "The recipient.country code field must be a string." | The value must be a string. |
| "recipient.countryCode": "The recipient.country code field must be at least 2 characters." | The string must be at least 2 characters long. |
| "recipient.countryCode": "The recipient.country code field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "recipient.countryCode": "The selected recipient.country code is invalid." | The value is not among the allowed values for this field. |
| "recipient.divisionId": "The recipient.division id field is required when none of recipient.address parts / recipient.address / recipient.division number are present." | Required when none of the following fields are provided: recipient.addressParts, recipient.address, recipient.divisionNumber. |
| "recipient.divisionId": "The recipient.division id field is required when recipient.address parts is not present." | Required when recipient.addressParts is not provided. |
| "recipient.divisionId": "The recipient.division id field must be an integer." | The value must be an integer. |
| "recipient.divisionId": "The recipient.division id must be a valid division ID (numeric ID or external ID)." | The value must be a valid division identifier (numeric ID or external ID). |
| "recipient.divisionNumber": "The recipient.division number field is required when none of recipient.address parts / recipient.address / recipient.division id are present." | Required when none of the following fields are provided: recipient.addressParts, recipient.address, recipient.divisionId. |
| "recipient.email": "The recipient.email field is required." | Required field — must be present in the request. |
| "recipient.email": "The recipient.email field must be a string." | The value must be a string. |
| "recipient.email": "The recipient.email field must be a valid email address." | The value must be a valid email address. |
| "recipient.email": "The recipient.email field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.eoriCode": "EORI code is incorrect" | Invalid EORI code. |
| "recipient.eoriCode": "The recipient.eori code field must be a string." | The value must be a string. |
| "recipient.eoriCode": "The recipient.eori code field must be at least 3 characters." | The string must be at least 3 characters long. |
| "recipient.eoriCode": "The recipient.eori code field must not be greater than 17 characters." | The string must be at most 17 characters long. |
| "recipient.latin": "The recipient.latin field must be true or false." | The value must be a boolean: true or false. |
| "recipient.name": "The recipient.name field is required." | Required field — must be present in the request. |
| "recipient.name": "The recipient.name field must be a string." | The value must be a string. |
| "recipient.name": "The recipient.name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "recipient.phone": "The recipient.phone field is required." | Required field — must be present in the request. |
| "recipient.phone": "The recipient.phone field must be a string." | The value must be a string. |
| "recipient.phone": "The recipient.phone field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "recipient.placeId": "The recipient.place id field must be a string." | The value must be a string. |
| "recipient.registrationAddress": "The recipient.registration address field must be a string." | The value must be a string. |
| "recipient.registrationAddressParts": "The recipient.registration address parts field must be an array." | The value must be an array. |
| "recipient.settlementId": "The recipient.settlement id field is required." | Required field — must be present in the request. |
| "recipient.settlementId": "The recipient.settlement id field must be an integer." | The value must be an integer. |
| "recipient.settlementId": "The recipient.settlement id field must be greater than 0." | The value must be greater than 0. |
| "recipientArchive": "The recipient archive field must be true or false." | The value must be a boolean: true or false. |
| "recipientCompanyTins": "The recipient company tins field must be an array." | The value must be an array. |
| "recipientCompanyTins.{n}": "The recipient company tins.{n} field must be a string." | The value must be a string. |
| "recipientCountryCode": "The recipient country code field must be a string." | The value must be a string. |
| "recipientCountryCode": "The recipient country code field must be at least 2 characters." | The string must be at least 2 characters long. |
| "recipientCountryCode": "The recipient country code field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "recipientDivisionCategory": "The recipient division category field must be an array." | The value must be an array. |
| "recipientDivisionCategory.{n}": "The recipient division category.{n} field must be a string." | The value must be a string. |
| "recipientDivisionCategory.{n}": "The selected recipient division category.{n} is invalid." | The value is not among the allowed values for this field. |
| "recipientServiceType": "The recipient service type field must be a string." | The value must be a string. |
| "recipientSettlementExternalId": "The recipient settlement external id field must be a string." | The value must be a string. |
| "recipientSettlementId": "The recipient settlement id field must be a string." | The value must be a string. |
| "refs": "The refs field is required." | Required field — must be present in the request. |
| "refs": "The refs field must be an array." | The value must be an array. |
| "refs": "The refs field must have at least 1 items." | The array must contain at least 1 item(s). |
| "refs": "The refs field must not have more than 100 items." | The array must contain at most 100 items. |
| "refs.{n}": "The refs.{n} field is required." | Required field — must be present in the request. |
| "refs.{n}": "The refs.{n} field must be a string." | The value must be a string. |
| "refs.{n}": "The refs.{n} field must be a valid UUID." | The value must be a valid UUID. |
| "regionId": "The region id field must be an integer." | The value must be an integer. |
| "registerNumber": "The register number field must be a string." | The value must be a string. |
| "requestId": "The request id field must be a string." | The value must be a string. |
| "reservationId": "The reservation id field is required." | Required field — must be present in the request. |
| "reservationId": "The reservation id field must be a string." | The value must be a string. |
| "reservationId": "The reservation id field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "rmsId": "The rms id field must be a string." | The value must be a string. |
| "rmsId": "The rms id field must not be greater than 8 characters." | The string must be at most 8 characters long. |
| "safePurchase": "The safe purchase field must be an integer." | The value must be an integer. |
| "scheduledDeliveryDateFrom": "The scheduled delivery date from field must be a date before or equal to scheduled delivery date to." | The value must be a date no later than scheduled delivery date to. |
| "scheduledDeliveryDateFrom": "The scheduled delivery date from field must be a string." | The value must be a string. |
| "scheduledDeliveryDateFrom": "The scheduled delivery date from field must have a value." | The field is present but empty — provide a value. |
| "scheduledDeliveryDateTo": "The scheduled delivery date to field must be a date after or equal to scheduled delivery date from." | The value must be a date no earlier than scheduled delivery date from. |
| "scheduledDeliveryDateTo": "The scheduled delivery date to field must be a string." | The value must be a string. |
| "scheduledDeliveryDateTo": "The scheduled delivery date to field must have a value." | The field is present but empty — provide a value. |
| "secretToken": "The secret token field format is invalid." | The value does not match the expected format of the field. |
| "secretToken": "The secret token field must be a string." | The value must be a string. |
| "secretToken": "The secret token field must not be greater than 600 characters." | The string must be at most 600 characters long. |
| "secretTokenHeaderName": "The secret token header name field must be a string." | The value must be a string. |
| "sendWarnings": "The send warnings field must be true or false." | The value must be a boolean: true or false. |
| "sender": "The sender field is required." | Required field — must be present in the request. |
| "sender": "The sender field must be an array." | The value must be an array. |
| "sender.address": "The sender.address field is required when none of sender.division id / sender.address parts / sender.division number are present." | Required when none of the following fields are provided: sender.divisionId, sender.addressParts, sender.divisionNumber. |
| "sender.addressParts": "The sender.address parts field is required when none of sender.division id / sender.address / sender.division number are present." | Required when none of the following fields are provided: sender.divisionId, sender.address, sender.divisionNumber. |
| "sender.companyName": "The sender.company name field is required." | Required field — must be present in the request. |
| "sender.companyName": "The sender.company name field must be a string." | The value must be a string. |
| "sender.companyName": "The sender.company name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.companyTin": "Access to the company is forbidden by API key." | Access to the specified company is forbidden for this API key. Check the key permissions for the sender company. |
| "sender.companyTin": "The sender.company tin field is required." | Required field — must be present in the request. |
| "sender.companyTin": "The sender.company tin field must be a string." | The value must be a string. |
| "sender.companyTin": "The sender.company tin field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "sender.countryCode": "The selected sender.country code is invalid." | The value is not among the allowed values for this field. |
| "sender.countryCode": "The sender.country code field is required." | Required field — must be present in the request. |
| "sender.countryCode": "The sender.country code field must be a string." | The value must be a string. |
| "sender.countryCode": "The sender.country code field must be at least 2 characters." | The string must be at least 2 characters long. |
| "sender.countryCode": "The sender.country code field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "sender.divisionId": "The sender.division id field is required when none of sender.address parts / sender.address / sender.division number are present." | Required when none of the following fields are provided: sender.addressParts, sender.address, sender.divisionNumber. |
| "sender.divisionId": "The sender.division id must be a valid division ID (numeric ID or external ID)." | The value must be a valid division identifier (numeric ID or external ID). |
| "sender.divisionNumber": "The sender.division number field is required when none of sender.address parts / sender.address / sender.division id are present." | Required when none of the following fields are provided: sender.addressParts, sender.address, sender.divisionId. |
| "sender.email": "The sender.email field is required." | Required field — must be present in the request. |
| "sender.email": "The sender.email field must be a string." | The value must be a string. |
| "sender.email": "The sender.email field must be a valid email address." | The value must be a valid email address. |
| "sender.email": "The sender.email field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.eoriCode": "EORI code is incorrect" | Invalid EORI code. |
| "sender.eoriCode": "The sender.eori code field must be a string." | The value must be a string. |
| "sender.eoriCode": "The sender.eori code field must be at least 3 characters." | The string must be at least 3 characters long. |
| "sender.eoriCode": "The sender.eori code field must not be greater than 17 characters." | The string must be at most 17 characters long. |
| "sender.ioss": "IOSSNumber is incorrect" | Invalid IOSS number. |
| "sender.ioss": "The sender.ioss field must be a string." | The value must be a string. |
| "sender.ioss": "The sender.ioss field must be at least 8 characters." | The string must be at least 8 characters long. |
| "sender.ioss": "The sender.ioss field must not be greater than 12 characters." | The string must be at most 12 characters long. |
| "sender.name": "The sender.name field is required." | Required field — must be present in the request. |
| "sender.name": "The sender.name field must be a string." | The value must be a string. |
| "sender.name": "The sender.name field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.phone": "The sender.phone field is required." | Required field — must be present in the request. |
| "sender.phone": "The sender.phone field must be a string." | The value must be a string. |
| "sender.phone": "The sender.phone field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "sender.registrationAddress": "The sender.registration address field must be a string." | The value must be a string. |
| "sender.registrationAddressParts": "The sender.registration address parts field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts": "The sender.registration address parts field must be an array." | The value must be an array. |
| "sender.registrationAddressParts.block": "The sender.registration address parts.block field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.block": "The sender.registration address parts.block field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "sender.registrationAddressParts.building": "The sender.registration address parts.building field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts.building": "The sender.registration address parts.building field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.building": "The sender.registration address parts.building field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "sender.registrationAddressParts.city": "The sender.registration address parts.city field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts.city": "The sender.registration address parts.city field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.city": "The sender.registration address parts.city field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.registrationAddressParts.flat": "The sender.registration address parts.flat field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.flat": "The sender.registration address parts.flat field must not be greater than 50 characters." | The string must be at most 50 characters long. |
| "sender.registrationAddressParts.postCode": "The sender.registration address parts.post code field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts.postCode": "The sender.registration address parts.post code field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.postCode": "The sender.registration address parts.post code field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "sender.registrationAddressParts.region": "The sender.registration address parts.region field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts.region": "The sender.registration address parts.region field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.region": "The sender.registration address parts.region field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.registrationAddressParts.street": "The sender.registration address parts.street field is required." | Required field — must be present in the request. |
| "sender.registrationAddressParts.street": "The sender.registration address parts.street field must be a string." | The value must be a string. |
| "sender.registrationAddressParts.street": "The sender.registration address parts.street field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "sender.settlementId": "The sender.settlement id field is required." | Required field — must be present in the request. |
| "sender.settlementId": "The sender.settlement id field must be an integer." | The value must be an integer. |
| "sender.settlementId": "The sender.settlement id field must be greater than 0." | The value must be greater than 0. |
| "senderArchive": "The sender archive field must be true or false." | The value must be a boolean: true or false. |
| "senderCompanyTins": "The sender company tins field must be an array." | The value must be an array. |
| "senderCompanyTins.{n}": "The sender company tins.{n} field must be a string." | The value must be a string. |
| "senderCountryCode": "The sender country code field must be a string." | The value must be a string. |
| "senderCountryCode": "The sender country code field must be at least 2 characters." | The string must be at least 2 characters long. |
| "senderCountryCode": "The sender country code field must not be greater than 2 characters." | The string must be at most 2 characters long. |
| "senderDivisionCategory": "The sender division category field must be an array." | The value must be an array. |
| "senderDivisionCategory.{n}": "The selected sender division category.{n} is invalid." | The value is not among the allowed values for this field. |
| "senderDivisionCategory.{n}": "The sender division category.{n} field must be a string." | The value must be a string. |
| "senderDivisionId": "The sender division id field must be an integer." | The value must be an integer. |
| "senderDivisionId": "The sender division id field must be at least 1." | The value must be at least 1. |
| "senderPhone": "The sender phone field must be a string." | The value must be a string. |
| "senderPhones": "The sender phones field must be an array." | The value must be an array. |
| "senderPhones": "The sender phones field must have at least 1 items." | The array must contain at least 1 item(s). |
| "senderServiceType": "The sender service type field must be a string." | The value must be a string. |
| "senderSettlementExternalId": "The sender settlement external id field must be a string." | The value must be a string. |
| "senderSettlementId": "The sender settlement id field must be a string." | The value must be a string. |
| "serviceAnnullingAmount": "The service annulling amount field must be a string." | The value must be a string. |
| "serviceCodes": "The service codes field must be an array." | The value must be an array. |
| "serviceCodes.{n}": "The service codes.{n} field must be a string." | The value must be a string. |
| "service_id": "The service id field is required." | Required field — must be present in the request. |
| "service_id": "The service id field must be a valid UUID." | The value must be a valid UUID. |
| "services": "The services field must be an array." | The value must be an array. |
| "services.{n}": "The services.{n} field must be an array." | The value must be an array. |
| "services.{n}": "The services.{n} field must have a value." | The field is present but empty — provide a value. |
| "services.{n}.additionalParameters": "The services.{n}.additional parameters field must be an array." | The value must be an array. |
| "services.{n}.additionalParameters": "The services.{n}.additionalParameters field is required." | Required field — must be present in the request. |
| "services.{n}.additionalParameters.cod.bankAccount.commissionPayer": "The selected services.{n}.additional parameters.cod.bank account.commission payer is invalid." | The value is not among the allowed values for this field. |
| "services.{n}.additionalParameters.cod.bankAccount.commissionPayer": "The services.{n}.additional parameters.cod.bank account.commission payer field must be a string." | The value must be a string. |
| "services.{n}.additionalParameters.height": "The services.{n}.additionalParameters.height field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.additionalParameters.length": "The services.{n}.additionalParameters.length field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.additionalParameters.parcelDescription": "The services.{n}.additionalParameters.parcelDescription field is required." | Required field — must be present in the request. |
| "services.{n}.additionalParameters.parcelsAmount": "The services.{n}.additionalParameters.parcelsAmount field is required." | Required field — must be present in the request. |
| "services.{n}.additionalParameters.parcelsAmount": "The services.{n}.additionalParameters.parcelsAmount field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.additionalParameters.totalActualWeight": "The services.{n}.additionalParameters.totalActualWeight field is required." | Required field — must be present in the request. |
| "services.{n}.additionalParameters.totalActualWeight": "The services.{n}.additionalParameters.totalActualWeight field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.additionalParameters.totalVolumetricWeight": "The services.{n}.additionalParameters.totalVolumetricWeight field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.additionalParameters.width": "The services.{n}.additionalParameters.width field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.amount": "The services.{n}.amount field is required." | Required field — must be present in the request. |
| "services.{n}.amount": "The services.{n}.amount field must be a number." | The value must be a number (decimals allowed). |
| "services.{n}.amount": "The services.{n}.amount field must be at least 0." | The value must be at least 0. |
| "services.{n}.amount": "The services.{n}.amount field must be at least 1." | The value must be at least 1. |
| "services.{n}.amount": "The services.{n}.amount field must be greater than 0." | The value must be greater than 0. |
| "services.{n}.contractNumber": "The services.{n}.contract number field is required." | Required field — must be present in the request. |
| "services.{n}.contractNumber": "The services.{n}.contract number field must be a string." | The value must be a string. |
| "services.{n}.contractNumber": "The services.{n}.contract number field must be at least 2 characters." | The string must be at least 2 characters long. |
| "services.{n}.contractNumber": "The services.{n}.contract number field must not be greater than 20 characters." | The string must be at most 20 characters long. |
| "services.{n}.deliveryDate": "The services.{n}.delivery date field must be a string." | The value must be a string. |
| "services.{n}.deliveryTime": "The services.{n}.delivery time field must be a string." | The value must be a string. |
| "services.{n}.payerType": "The selected services.{n}.payer type is invalid." | The value is not among the allowed values for this field. |
| "services.{n}.payerType": "The services.{n}.payer type field is required." | Required field — must be present in the request. |
| "services.{n}.payerType": "The services.{n}.payer type field must be a string." | The value must be a string. |
| "services.{n}.serviceCode": "The services.{n}.service code field is required." | Required field — must be present in the request. |
| "services.{n}.serviceCode": "The services.{n}.service code field must be a string." | The value must be a string. |
| "services.{n}.serviceId": "The services.{n}.service id field must be a string." | The value must be a string. |
| "services.{n}.serviceName": "The services.{n}.service name field must be a string." | The value must be a string. |
| "services.{n}.shipmentParcelRowNumber": "The services.{n}.shipment parcel row number field must be an integer." | The value must be an integer. |
| "services.{n}.shipmentParcelRowNumber": "The services.{n}.shipment parcel row number field must be greater than 0." | The value must be greater than 0. |
| "settlementId": "The settlement id field must be an integer." | The value must be an integer. |
| "settlementIds": "The settlement ids field must be an array." | The value must be an array. |
| "settlementIds.{n}": "The settlement ids.{n} field must be a string." | The value must be a string. |
| "settlementIds.{n}": "The settlementIds.{n} field must be an integer." | The value must be an integer. |
| "settlementIds.{n}": "The settlementIds.{n} field must be greater than 0." | The value must be greater than 0. |
| "shipmentId": "The shipment id field is required." | Required field — must be present in the request. |
| "shipmentId": "The shipment id field must be an integer." | The value must be an integer. |
| "shipmentId": "The shipment id field must be at least 1." | The value must be at least 1. |
| "shipmentIds": "The shipment ids field must be an array." | The value must be an array. |
| "shipmentIds.{n}": "The shipment ids.{n} field must be a string." | The value must be a string. |
| "shipmentNumber": "The shipment number field is required." | Required field — must be present in the request. |
| "shipmentNumber": "The shipment number field must be an array." | The value must be an array. |
| "shipmentNumber.{n}": "The shipment number.{n} field must be a string." | The value must be a string. |
| "shipmentTypes": "The selected shipment types is invalid." | The value is not among the allowed values for this field. |
| "shipmentTypes": "The shipment types field must be an array." | The value must be an array. |
| "shipments": "Shipments must be an array." | The list of shipments must be an array. |
| "shipments": "Shipments must be either all IDs or all numbers." | The list of shipments must contain either only identifiers or only numbers — they cannot be mixed. |
| "shipments": "Shipments must not be empty." | The list of shipments must not be empty. |
| "shipments": "The shipments field is required." | Required field — must be present in the request. |
| "shipments": "The shipments field must be an array." | The value must be an array. |
| "shipments": "The shipments field must have at least 1 item." | The array must contain at least 1 item(s). |
| "shipments": "The shipments field must not have more than 255 items." | The array must contain at most 255 items. |
| "shipments": "unavailable_operation" | The operation is not available for the current set of shipments. |
| "shipments.{n}": "The shipments.{n} field is required." | Required field — must be present in the request. |
| "shipments.{n}": "The shipments.{n} field must be a string." | The value must be a string. |
| "shipments.{n}.shipmentId": "The shipments.{n}.shipment id field is required." | Required field — must be present in the request. |
| "shipments.{n}.shipmentId": "The shipments.{n}.shipment id field must be an integer." | The value must be an integer. |
| "shipments.{n}.shipmentId": "The shipments.{n}.shipment id field must be at least 1." | The value must be at least 1. |
| "size": "The size field must be an integer." | The value must be an integer. |
| "size": "The size field must be at least 1." | The value must be at least 1. |
| "sort": "The sort field must be an array." | The value must be an array. |
| "sort": "The sort field must have a value." | The field is present but empty — provide a value. |
| "source": "The source field is required." | Required field — must be present in the request. |
| "source": "The source field must be a string." | The value must be a string. |
| "sources": "The sources field must be an array." | The value must be an array. |
| "sources.{n}": "The selected sources.{n} is invalid." | The value is not among the allowed values for this field. |
| "sources.{n}": "The sources.{n} field must be a string." | The value must be a string. |
| "state": "The selected state is invalid." | The value is not among the allowed values for this field. |
| "state": "The state field is required." | Required field — must be present in the request. |
| "state": "The state field must be a string." | The value must be a string. |
| "statements.{n}": "The statements.{n} field must be a file of type: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml." | The file must be one of the following types: jpeg, jpg, bmp, png, gif, svg, pdf, doc, docx, xlsx, pptx, csv, xlsb, xltx, xls, xlt, xml. |
| "statements.{n}": "The statements.{n} field must not be greater than 4096 kilobytes." | The file size must not exceed 4096 KB. |
| "status": "The selected status is invalid." | The value is not among the allowed values for this field. |
| "status": "The status field is required." | Required field — must be present in the request. |
| "status": "The status field must be a string." | The value must be a string. |
| "statuses": "The statuses field must be an array." | The value must be an array. |
| "statuses.{n}": "The selected statuses.{n} is invalid." | The value is not among the allowed values for this field. |
| "statuses.{n}": "The statuses.{n} field must be a string." | The value must be a string. |
| "subcategory": "The subcategory field must be a string." | The value must be a string. |
| "subcategory": "The subcategory field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "textSearch": "The text search field must be a string." | The value must be a string. |
| "textSearch": "The text search field must be at least 1 characters." | The string must be at least 1 characters long. |
| "textSearch": "The text search field must be at least 3 characters." | The string must be at least 3 characters long. |
| "textSearch": "The text search field must not be greater than 255 characters." | The string must be at most 255 characters long. |
| "thirdPartyPayerCodes": "The third party payer codes field must be an array." | The value must be an array. |
| "thirdPartyPayerCodes.{n}": "The thirdPartyPayerCodes.{n} field is required." | Required field — must be present in the request. |
| "thirdPartyPayerCodes.{n}": "The thirdPartyPayerCodes.{n} field must be a string." | The value must be a string. |
| "thirdPartyPayerCodesNotEmpty": "The third party payer codes not empty field must be true or false." | The value must be a boolean: true or false. |
| "timeIntervalEnd": "The time interval end field must be a string." | The value must be a string. |
| "timeIntervalStart": "The time interval start field must be a string." | The value must be a string. |
| "topRightLatitude": "The top right latitude field is required when topRightLongitude / bottomLeftLatitude / bottomLeftLongitude is present." | Required when any of the following fields is provided: topRightLongitude, bottomLeftLatitude, bottomLeftLongitude. |
| "topRightLongitude": "The top right longitude field is required when topRightLatitude / bottomLeftLatitude / bottomLeftLongitude is present." | Required when any of the following fields is provided: topRightLatitude, bottomLeftLatitude, bottomLeftLongitude. |
| "totalInsuranceCostFrom": "The total insurance cost from field must be a number." | The value must be a number (decimals allowed). |
| "totalInsuranceCostFrom": "The total insurance cost from field must be at least 0.01." | The value must be at least 0.01. |
| "totalInsuranceCostFrom": "The total insurance cost from field must be less than or equal to total insurance cost to." | The value must be no greater than total insurance cost to. |
| "totalInsuranceCostFrom": "The total insurance cost from field must have a value." | The field is present but empty — provide a value. |
| "totalInsuranceCostFrom": "The total insurance cost from field must not be greater than 10000000." | The value must be at most 10000000. |
| "totalInsuranceCostTo": "The total insurance cost to field must be a number." | The value must be a number (decimals allowed). |
| "totalInsuranceCostTo": "The total insurance cost to field must be at least 0.01." | The value must be at least 0.01. |
| "totalInsuranceCostTo": "The total insurance cost to field must be greater than or equal to total insurance cost from." | The value must be no less than total insurance cost from. |
| "totalInsuranceCostTo": "The total insurance cost to field must have a value." | The field is present but empty — provide a value. |
| "totalInsuranceCostTo": "The total insurance cost to field must not be greater than 10000000." | The value must be at most 10000000. |
| "totalStrategy": "The selected total strategy is invalid." | The value is not among the allowed values for this field. |
| "totalWeightFrom": "The total weight from field must be a number." | The value must be a number (decimals allowed). |
| "totalWeightFrom": "The total weight from field must be at least 0.01." | The value must be at least 0.01. |
| "totalWeightFrom": "The total weight from field must be less than or equal to total weight to." | The value must be no greater than total weight to. |
| "totalWeightFrom": "The total weight from field must have a value." | The field is present but empty — provide a value. |
| "totalWeightFrom": "The total weight from field must not be greater than 100000." | The value must be at most 100000. |
| "totalWeightTo": "The total weight to field must be a number." | The value must be a number (decimals allowed). |
| "totalWeightTo": "The total weight to field must be at least 0.01." | The value must be at least 0.01. |
| "totalWeightTo": "The total weight to field must be greater than or equal to total weight from." | The value must be no less than total weight from. |
| "totalWeightTo": "The total weight to field must have a value." | The field is present but empty — provide a value. |
| "totalWeightTo": "The total weight to field must not be greater than 100000." | The value must be at most 100000. |
| "trackingDateFrom": "The tracking date from field is required when none of ids / numbers are present." | Required when none of the following fields are provided: ids, numbers. |
| "trackingDateFrom": "The tracking date from field must be a valid date." | The value must be a valid date. |
| "trackingDateTo": "The tracking date to field is required when none of ids / numbers are present." | Required when none of the following fields are provided: ids, numbers. |
| "trackingDateTo": "The tracking date to field must be a valid date." | The value must be a valid date. |
| "trackingStatusCode": "The tracking status code field must be an integer." | The value must be an integer. |
| "trackingStatusCode": "The tracking status code field must be at least 1." | The value must be at least 1. |
| "trackingStatusCodes": "The tracking status codes field must be an array." | The value must be an array. |
| "trackingStatusCodes.{n}": "The tracking status codes.{n} field must be an integer." | The value must be an integer. |
| "trackingStatusCodes.{n}": "The tracking status codes.{n} field must be at least 1." | The value must be at least 1. |
| "trackingStatusCodes.{n}": "The tracking status codes.{n} field must have a value." | The field is present but empty — provide a value. |
| "trademarkUrl": "The trademark url field must be a string." | The value must be a string. |
| "type": "The selected type is invalid." | The value is not among the allowed values for this field. |
| "type": "The type field is required." | Required field — must be present in the request. |
| "type": "The type field must be a string." | The value must be a string. |
| "types": "The selected types is invalid." | The value is not among the allowed values for this field. |
| "types": "The types field must be an array." | The value must be an array. |
| "types.{n}": "The types.{n} field is required." | Required field — must be present in the request. |
| "types.{n}": "The types.{n} field must be a string." | The value must be a string. |
| "updatePartial": "The update partial field must be true or false." | The value must be a boolean: true or false. |
| "url": "The url field is required." | Required field — must be present in the request. |
| "url": "The url field must be a string." | The value must be a string. |
| "useModificationsRecipientPhone": "The use modifications recipient phone field must be true or false." | The value must be a boolean: true or false. |
| "uuid": "The uuid field is required." | Required field — must be present in the request. |
| "uuid": "The uuid field must be a valid UUID." | The value must be a valid UUID. |
| "verifiedWithDiia": "The verified with diia field must be true or false." | The value must be a boolean: true or false. |
| "warningEmail": "The warning email field must be a string." | The value must be a string. |
| "withAllParcels": "The with all parcels field must be true or false." | The value must be a boolean: true or false. |
| "withExternalProviders": "The with external providers field must be true or false." | The value must be a boolean: true or false. |
| "withShipmentsInfo": "The with shipments info field must be true or false." | The value must be a boolean: true or false. |
| "shipment_not_found" | The shipment was not found for the specified number while retrieving a claim. Check that the shipment number is correct. |
| "The conditions for creating an international light return are not met" | Possible reasons:
|
| "company": "not_found" | Company not found or could not be verified using the provided information. |
| "App\Dictionary\Domain\Contract\ContractEntity.number": "validation.exists" | Mentioned cotract number doesn’t exist, please check your data or contact support / your sales manager |
| Message | Description |
|---|---|
| "Too Many Attempts." | The per-minute request limit has been exceeded. Reduce the request rate and retry later. |
| Message | Description |
|---|---|
| "timeout error" | A temporary unavailability or timeout of an internal service. Try again later. |
Open PlaygroundQuick StartAPI Reference
Two variantsMap view (Google Maps) or Widget view (list with search and filters). Both support the same params and events. |
Lazy iframe initThe |
No API key neededAll Nova Post API calls go through the proxy server. |
| PARAM | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| container | string | HTMLElement | Yes | — | CSS selector or DOM element to mount into |
| locale | 'uk' | 'en' | 'de' | 'cs' | — | 'uk' | UI language |
| variant | 'map' | 'widget' | — | 'map' | Display mode: map or list with filters |
| viewMode | 'container' | 'popup' | — | 'container' | Inline embed or modal popup |
| country | string | null | — | — | ISO country code, e.g. 'UA' |
| city | string | null | — | — | City name to pre-select |
| senderCountry | string | null | — | — | Sender ISO country code, e.g. 'UA'; unlocks partner PUDO (UPS) selection for allowed countries [PL, UA] |
| divisionId | number | null | — | — | Pre-select a specific division |
| divisionCategories | DivisionType[] | — | — | Filter by type; all shown if omitted |
| autoShow | boolean | — | false | Call show() automatically after init |
| mobileBreakpointPx | number | — | 768 | Fullscreen popup below this viewport width |
| onSelect | (division: DivisionItem) => void | — | — | Fires when user confirms a division |
| onReady | () => void | — | — | Fires when iframe is loaded and ready |
| onError | (error: Error) => void | — | — | Fires on runtime error inside iframe |
| onClose | (reason?) => void | — | — | Fires when popup is closed |
| VARIANT | VIEWMODE | RESULT |
|---|---|---|
| map | container | Google Maps embedded inline in your page |
| map | popup | Trigger button → click opens popup with Google Maps |
| widget | container | Division list with search embedded inline |
| widget | popup | Trigger button → click opens popup with division list |
| Service | Purpose |
|---|---|
| Psr\Log\LoggerInterface | Custom logging |
| Psr\Http\Client\ClientInterface | Custom HTTP client configuration |
| NovaDigital\NovaPost\Storage\JwtTokenStorageInterface | Custom JWT token storage |
| NovaDigital\NovaPost\Http\ResponseHandlerInterface | Custom response processing |
| NovaDigital\NovaPost\Http\RetryHandlerInterface | Custom retry logic |
| Standard | Purpose |
|---|---|
| PSR-4: Autoloader | For class autoloading |
| PSR-11: Container Interface | For a flexible dependency container |
| PSR-3: Logger Interface | Allows using any compatible logger |
| PSR-7: HTTP Message Interface | Used for all API requests and responses |
| PSR-18: HTTP Client | For sending HTTP requests |
| PSR-17: HTTP Factories | For creating PSR-7 messages |
| PSR-12: Extended Coding Standard | For coding style |
.../ui/v.1.0/shipments/calculations
.../v.1.0/shipments/calculations
.../ui/site/v.1.0/shipments/delivery-calculations
.../ui/v.1.0/shipments/delivery-calculations
.../mobileapp/v.1.1/shipments/calculations
Status of shipment
Allowed: ReadyToShip
| | | **payerType** | enum |Identifies who is responsible for the payment of delivery services. Determines which party bears the cost: Sender, Recipient, or ThirdPerson. Required payerContractNumber for shipments within Europe or from Europe to Ukraine.
Allowed: Sender┃Recipient┃ThirdPerson
\* for route /shipments/delivery-calculations - the request response will always return payerType = Sender
Type of tax calculation.
Example: DAP | DDP.
Declared value of shipment for customs duty deduction. Also indicates maximum compensation in case of loss/damage.
Requiered if incoterm = “DDP”
Limit: Min. 1
| | | **payerFeesCustoms** | enum |Identifies who is responsible for the customs payments. Determines which party bears the cost: Sender, Recipient, or ThirdPerson.
Allowed: Sender┃Recipient┃ThirdPerson
| | | **parcels** | array of object | An array of parcel objects representing distinct packages within the shipment, including dimensions, weight, and details for delivery cost calculation. | | | **cargoCategory** | enum |Specifies the type of shipment. Categories: parcel, documents, cargo. Affects shipping method, cost, and documentation.
Allowed: parcel┃documents┃cargo
| | | **insuranceCost** | number |Declared value of shipment for insurance coverage. Indicates maximum compensation in case of loss/damage.
Constraints: Min 1
| | | **rowNumber** | integer |Sequential identifier for each parcel in the shipment.
If only one parcel, value = 1.
Constraints: Min 1
| | | **width** | integer |Parcel width in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **length** | integer |Parcel length in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **height** | integer |Parcel height in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **actualWeight** | integer |Real parcel weight in grams. Round to nearest 10 g before sending.
Constraints: Min 1┃Max 2147483647
| | | **sender** | object | Information about the sender. Includes origin details, affects logistics and cost calculations. | | | **divisionNumber** | string┃null | Optional sender post office division number. Interchangeable with divisionId/ postCode | | | **divisionId** | integer┃null | Optional sender division code. Interchangeable with divisionNumber / postCode | | | **addressParts** | object | Required when shipping from an address. Contains detailed address components. | | | **postCode** | string |Postal/ZIP code of sender.
Constraints: Max 10 chars
| | | **recipient** | object | Information about the party receiving the shipment. | | | **countryCode** | string |ISO 3166-1 Alpha-2 code for recipient’s country.
Pattern: ^\[A-Z]{2}$
| | | **divisionNumber** | string┃null | Optional recipient post office division number. Interchangeable with divisionId / postCode | | | **divisionId** | integer┃null | Optional recipient division code. Interchangeable with divisionNumber / postCode | | | **addressParts** | object | Required when delivering to a specific address. Contains detailed address fields. | | | **postCode** | string |Postal/ZIP code for recipient.
Constraints: Max 10 chars
| | ### Acceptable HTTP status codes response | **HTTP-code** | **Status** | **Description** | | ------------- | -------------------- | ------------------------------------------------------------------------------ | | 200 | OK | Request successful. The server has responded as required. | | 422 | Unprocessable entity | The request was well-formed but had semantic errors + the reason for the error | {% @nova-post-newsletter/subscribe %} # Added shipment registry management methods ## Registers in Europe **Restrictions:** * are created only for shipments that are in ReadyToShip status; * there is only one shipping point for all shipments in the registry; * the user performing operations with the registry is associated with the sender organization (for legal entities) or is the sender in the shipments; * the maximum number of shipments in the registry is 100. ### Creating a new registry with shipment This method is used to create a client registry for shipments from Europe. #### Request The Method `POST v.1.0/registry` ``` { "description": "My_new_registry", "shipments": [ "SHPL0462195188" ] } ``` #### Response The state`200 OK Request successful. The server responded as required.` ``` { "id": "948086", "number": "CRPL0000041723", "versionTracking": null, "status": "Open", "createdAt": "2026-05-19T14:46:28.232180Z", "updatedAt": "2026-05-19T14:46:28.232180Z", "deletedAt": null, "posted": null, "printed": null, "scannedBarcodesAmount": 1, "forScanBarcodesAmount": 0, "description": "My_new_registry", "senderCompanyId": null, "senderCompanyTin": "", "senderPhone": "48512345678", "senderCountryCode": "PL", "senderSettlementId": "22326", "senderSettlementExternalId": null, "senderSettlementName": "Warsaw", "senderDivisionId": "1888318", "senderDivisionExternalId": null, "senderDivisionName": "Post branch 11", "senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ", "senderAddressParts": { "city": "Warszawa", "region": "Warszawa County", "street": "Stanisława Wojciechowskiego", "streetId": null, "postCode": "02-495", "building": "39 lok.1", "flat": "", "block": "", "latitude": 52.1947201268, "longitude": 20.8706685393, "note": "", "addressId": null }, "shipments": [ { "shipmentId": "1401932", "shipmentNumber": "SHPL0462195188", "destinationDivision": { "name": "WARSZAWA 11", "id": 1888318, "number": "02/11" } } ] } ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Adding a shipment to an existing registry #### Description This method is used to add a shipment to an existing client registry. #### Query Parameter {id} - unique identifier of the registry #### Request The method`POST v.1.0/registry/{id}/shipments` ``` { "shipments": [ "SHPL8187197311" ] } ``` #### Response The state `200 OK Request successful. The server has responded as required.` ``` { "id": "948086", "number": "CRPL0000041723", "versionTracking": null, "status": "Open", "createdAt": "2026-05-19T14:46:28.232000Z", "updatedAt": "2026-05-19T14:46:28.574000Z", "deletedAt": null, "posted": false, "printed": false, "scannedBarcodesAmount": 2, "description": "My_new_registry", "senderCompanyId": null, "senderCompanyTin": "", "senderPhone": "48512345678", "senderCountryCode": "PL", "senderSettlementId": "22326", "senderSettlementExternalId": null, "senderSettlementName": "Warsaw", "senderDivisionId": "1888318", "senderDivisionExternalId": null, "senderDivisionName": "Post branch 11", "senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ", "senderAddressParts": { "city": "Warszawa", "region": "Warszawa County", "street": "Stanisława Wojciechowskiego", "streetId": null, "postCode": "02-495", "building": "39 lok.1", "flat": "", "block": "", "latitude": 52.1947201268, "longitude": 20.8706685393, "note": null, "addressId": null }, "shipments": [ { "shipmentId": "3168550", "shipmentNumber": "SHPL0462195188" }, { "shipmentId": "3168827", "shipmentNumber": "SHPL8187197311" } ] } ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Removing a shipment from the registry #### Description This method removes a shipment from an existing client registry. #### Query Parameter {id} - unique identifier of the registry #### Request The method`DELETE v.1.0/registry/{id}/shipments` ``` { "shipments": [ "SHPL8187197311" ] } ``` #### Response The state `200 OK Request successful. The server has responded as required.` ``` { "id": "948086", "number": "CRPL0000041723", "versionTracking": null, "status": "Open", "createdAt": "2026-05-19T14:46:28.232000Z", "updatedAt": "2026-05-19T14:46:28.574000Z", "deletedAt": null, "posted": false, "printed": false, "scannedBarcodesAmount": 2, "description": "My_new_registry", "senderCompanyId": null, "senderCompanyTin": "", "senderPhone": "48512345678", "senderCountryCode": "PL", "senderSettlementId": "22326", "senderSettlementExternalId": null, "senderSettlementName": "Warsaw", "senderDivisionId": "1888318", "senderDivisionExternalId": null, "senderDivisionName": "Post branch 11", "senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ", "senderAddressParts": { "city": "Warszawa", "region": "Warszawa County", "street": "Stanisława Wojciechowskiego", "streetId": null, "postCode": "02-495", "building": "39 lok.1", "flat": "", "block": "", "latitude": 52.1947201268, "longitude": 20.8706685393, "note": null, "addressId": null }, "shipments": [ { "shipmentId": "3168550", "shipmentNumber": "SHPL0462195188" } ] } ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Deleting the registry #### Description This method completely deletes the client registry, but first you need to delete all shipments. #### Query Parameter {id} - unique identifier of the registry #### Request The method`DELETE v.1.0/registry/{id}` #### Response ``` { "success": true } ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Renaming the registry #### Description This method renames an existing client registry. #### Query Parameter {id} - unique identifier of the registry #### Request The method`PUT v.1.0/registry/{id}/rename` ``` { "description": "new name" } ``` #### Response The state `200 OK Request successful. The server has responded as required.` ``` { "id": "948086", "number": "CRPL0000041723", "versionTracking": null, "status": "Open", "createdAt": "2026-05-19T14:46:28.232000Z", "updatedAt": "2026-05-19T14:46:28.574000Z", "deletedAt": null, "posted": false, "printed": false, "scannedBarcodesAmount": 1, "description": "new name", "senderCompanyId": null, "senderCompanyTin": "", "senderPhone": "48512345678", "senderCountryCode": "PL", "senderSettlementId": "22326", "senderSettlementExternalId": null, "senderSettlementName": "Warsaw", "senderDivisionId": "1888318", "senderDivisionExternalId": null, "senderDivisionName": "Post branch 11", "senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ", "senderAddressParts": { "city": "Warszawa", "region": "Warszawa County", "street": "Stanisława Wojciechowskiego", "streetId": null, "postCode": "02-495", "building": "39 lok.1", "flat": "", "block": "", "latitude": 52.1947201268, "longitude": 20.8706685393, "note": null, "addressId": null }, "shipments": [ { "shipmentId": "3168550", "shipmentNumber": "SHPL0462195188" } ] } ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Printing the registry #### Description This method returns a file for printing the client registry #### Query Parameter {id} - unique identifier of the registry #### Request The method`GET v.1.0/registry/print?id=948086` #### Response The state `200 OK Request successful. The server has responded as required.` ``` file ``` #### Errors | **Error** | **Meaning** | | --------- | ------------------- | | 401 | Unauthorized | | 422 | Validation error | | 503 | Connection time-out | ### Requesting a list of registries #### Description Цей метод повертає список реєстрів по заданим користувачем фільтрам. #### Query Parameter | **Field** | **Type** | **Possible Value** | **Description** | | ----------------- | -------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isEURegistry | boolean | true | Mandatory parameter for European registers. | | ids\[] | string | **Example:** 948086 | Unique registry identifiers for which information should be obtained. | | numbers\[] | string | **Example:** CRPL0000041723 | Unique registry number for which information should be obtained. | | settlementIds\[] | string | **Example:** 22326 | Unique identifier of the settlement. | | withShipmentsInfo | boolean | **Example:** true | When this parameter is specified, the shipment information array will include the shipment ID, shipment number, total weight, total value, invoice currency (if available), and invoice availability. If the parameter is not specified or is set to false, the shipments block will contain only the shipment ID and shipment number. | | createdAtFrom | date | **Example:** 01.05.2026 | Start date of the registry filtering period. Used to retrieve records created from this date inclusive. The field `createdAtFrom` must be a date earlier than `createdAtTo` | | createdAtTo | date | **Example:** 20.05.2026 | End date of the registry filtering period. Used to retrieve records created before this date (exclusive). | | page | integer | **Example:** 1 | Page number to return. | | limit | integer | **Example:** 5 | Maximum number of items to return per page. | #### Request The method`GET v.1.0/registry` ``` { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1, "items": [ { "id": "948086", "number": "CRPL0000041723", "createdAt": "2026-05-19T14:46:28.232000Z", "updatedAt": "2026-05-20T07:01:01.787000Z", "deletedAt": null, "posted": false, "printed": false, "description": "new name", "status": "Open", "type": "Client", "createdByUser": "255ea89d-8c1f-47ec-8f2e-64486bd24f5f", "scannedBarcodesAmount": 0, "source": "clientapi", "companyId": null, "companyTin": "", "companyName": "Private person", "fullName": "Oksana Hrechaniuk", "phone": "48512345678", "countryCode": "PL", "country": "Poland", "settlementId": "22326", "settlementName": "Warsaw", "divisionId": "1888318", "divisionName": "Post branch 11", "address": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ", "addressParts": { "city": "Warszawa", "region": "Warszawa County", "street": "Stanisława Wojciechowskiego", "streetId": null, "postCode": "02-495", "building": "39 lok.1", "flat": "", "block": "", "latitude": 52.1947201268, "longitude": 20.8706685393, "note": null, "addressId": null }, "currencyCode": "PLN", "shipmentsInfo": [ { "id": "3168550", "number": "SHPL0462195188", "totalWeight": 2000, "totalCost": 65, "currencyCode": "PLN", "invoice": true } ] } ] } ``` # Added custom invoice attachments for business shipments **Endpoint:** POST v.1.0/shipments PUT v.1.0/shipments/{id} In accordance with customs requirements, starting from April 15, corporate clients will be able to additionally upload their own invoice form with a physical signature or a completed, signed, and scanned invoice template to the international express waybill in order to ensure proper cargo documentation support. What’s new? Previously, clients could attach their own invoice forms, but customs officers identified them only after the physical inspection of the cargo. There was also a risk of incorrect invoice type identification (commercial invoice or invoice issued free of charge), which could cause delays in customs clearance processing. Now, within the `invoice` array, you can: * specify whether the invoice is client-provided; * define the invoice type and its attributes; * attach a scanned invoice file. This allows the system to automatically determine the correct customs codes and synchronize data between the client, Nova Post systems, and customs authorities. Additionally, in this scenario, the client must provide a flag confirming that the invoice has been physically signed. How it works: New fields for attaching a client invoice have been added to the request for creating or updating an international express waybill. The system identifies the presence of a client invoice and transfers this information to the customs broker. Please note that this functionality is available both for: * creating an international express waybill; * updating an international express waybill. | Field name | Type | Description | | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientInvoice` | int |Indicates whose invoice is used.
1 — client invoice
0 — Nova Post template
Default value: 0
Invoice type:
Invoice — commercial invoice
ProformaInvoice — free-of-charge invoice
Default value: Invoice
Client invoice number (for client invoice).
Required if clientInvoice = 1
Client invoice date (for client invoice).
Default value: current date
| | `invoiceSign` | int |Indicates that the client signed the invoice file.
Required if clientInvoice = 1
File content in Base64 format.
Required if clientInvoice = 1
Client-defined file name.
Required if clientInvoice = 1
DELETE /ui/v.1.0/shipments/{id}
DELETE /v.1.0/shipments/{id}
DELETE /mobileapp/v.1.1/shipments/{id}
DELETE /cbc/v.1.0/shipments/{id}
DELETE /internal/awis/shipments/{id}
| | **Change Type** | existing endpoint update | | **Authorization** | Authorization: Bearer jwt-token… | | **Related Task** |/v.1.0/shipments/calculations/mobileapp/v.1.1/shipments/calculations/ui/v.1.0/shipments/calculations ui/v.1.0/shipments/delivery-calculationsui/site/v.1.0/shipments/delivery-calculations
Shipment creation
Shipment update
POST
PUT
POST:/v.1.0/shipments/ui/v.1.0/shipments/mobileapp/v.1.1/shipments
PUT:/v.1.0/shipments/{id}/ui/v.1.0/shipments/{id}/mobileapp/v.1.1/shipments
Alpha-code of country
Example: PL - alpha-code of Poland
| ### Request and response parameters Request .../v.1.0/dictionary/customs-fees/{code}Response .../v.1.0/dictionary/customs-fees/{code} ### Shema | **Field** | **Type** | **Description** | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | customFeeActive | boolean |Indication of the possibility of payment of customs duties by the sender.
Possible values
true - payment is possible
false - payment is not possible
| | declaredCost | number | The maximum amount of the parcel value in the currency of the recipient's country for which the sender can pay customs duties. | ### Acceptable HTTP status codes response | **HTTP-code** | **Status** | **Description** | | ------------- | -------------------- | --------------------------------------------------------- | | 200 | OK | Request successful. The server has responded as required. | | 422 | Unprocessable entity | ErrorMessage: "The selected country is invalid." | # GET /registry/print ### General Information | **Method name** | The method of printing parcel registers | | ---------------- | --------------------------------------- | | **Direction** | EU, UA | | **HTTP Method** | GET | | **Route(s)** | `/v.1.0/registry/print/?id={id}` | | **Autorization** | `Authorization: Bearer jwt-token…` | ### Description The method allows users to receive a generated PDF file of a registry for further printing. **European registers** use only general registry type printing.\ **Ukrainian registers** (UA-World) can print\ \- general registry and\ \- international express waybills (IEW),\ \- markings of international express waybills,\ \- invoices of international express waybills.\internationalinvoicemarkingsize\_100\_100size of printed marking, mandatory fortype= marking
Number of copies of printed document (optional)
Default value: 1
.../ui/v.1.0/shipments/calculations
.../v.1.0/shipments/calculations
.../ui/site/v.1.0/shipments/delivery-calculations
.../ui/v.1.0/shipments/delivery-calculations
.../mobileapp/v.1.1/shipments/calculations
Status of shipment
Allowed: ReadyToShip
| | | **payerType** | enum |Identifies who is responsible for the payment of delivery services. Determines which party bears the cost: Sender, Recipient, or ThirdPerson. Required payerContractNumber for shipments within Europe or from Europe to Ukraine.
Allowed: Sender┃Recipient┃ThirdPerson
\* for route /shipments/delivery-calculations - the request response will always return payerType = Sender
Type of tax calculation.
Example: DAP | DDP.
Declared value of shipment for customs duty deduction. Also indicates maximum compensation in case of loss/damage.
Requiered if incoterm = “DDP”
Limit: Min. 1
| | | **payerFeesCustoms** | enum |Identifies who is responsible for the customs payments. Determines which party bears the cost: Sender, Recipient, or ThirdPerson.
Allowed: Sender┃Recipient┃ThirdPerson
| | | **parcels** | array of object | An array of parcel objects representing distinct packages within the shipment, including dimensions, weight, and details for delivery cost calculation. | | | **cargoCategory** | enum |Specifies the type of shipment. Categories: parcel, documents, cargo. Affects shipping method, cost, and documentation.
Allowed: parcel┃documents┃cargo
| | | **insuranceCost** | number |Declared value of shipment for insurance coverage. Indicates maximum compensation in case of loss/damage.
Constraints: Min 1
| | | **rowNumber** | integer |Sequential identifier for each parcel in the shipment.
If only one parcel, value = 1.
Constraints: Min 1
| | | **width** | integer |Parcel width in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **length** | integer |Parcel length in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **height** | integer |Parcel height in millimeters. Used to calculate volume.
Constraints: Min 1
| | | **actualWeight** | integer |Real parcel weight in grams. Round to nearest 10 g before sending.
Constraints: Min 1┃Max 2147483647
| | | **sender** | object | Information about the sender. Includes origin details, affects logistics and cost calculations. | | | **divisionNumber** | string┃null | Optional sender post office division number. Interchangeable with divisionId/ postCode | | | **divisionId** | integer┃null | Optional sender division code. Interchangeable with divisionNumber / postCode | | | **addressParts** | object | Required when shipping from an address. Contains detailed address components. | | | **postCode** | string |Postal/ZIP code of sender.
Constraints: Max 10 chars
| | | **recipient** | object | Information about the party receiving the shipment. | | | **countryCode** | string |ISO 3166-1 Alpha-2 code for recipient’s country.
Pattern: ^\[A-Z]{2}$
| | | **divisionNumber** | string┃null | Optional recipient post office division number. Interchangeable with divisionId / postCode | | | **divisionId** | integer┃null | Optional recipient division code. Interchangeable with divisionNumber / postCode | | | **addressParts** | object | Required when delivering to a specific address. Contains detailed address fields. | | | **postCode** | string |Postal/ZIP code for recipient.
Constraints: Max 10 chars
| | ### Acceptable HTTP status codes response | **HTTP-code** | **Status** | **Description** | | ------------- | -------------------- | ------------------------------------------------------------------------------ | | 200 | OK | Request successful. The server has responded as required. | | 422 | Unprocessable entity | The request was well-formed but had semantic errors + the reason for the error | # Popular integration Ready-made Nova Post integrations allow you to quickly connect delivery services to popular e-commerce platforms without the need to develop a full API integration from scratch. Use ready solutions for automatic shipment creation, order data transfer, and delivery status tracking. #### Available Integrations #### [BaseLinker](https://login.baselinker.com/) Integration for centralized order management from marketplaces, CRM systems, and e-commerce platforms. Allows creating Nova Post shipments directly from the BaseLinker interface. #### [Shopify](https://apps.shopify.com/nova-post-1?search_id=7bc00069-e4d9-4fb6-8e9e-6b17223ad373\&surface_detail=Nova+post\&surface_inter_position=1\&surface_intra_position=5\&surface_type=search) Integration for online stores built on Shopify. It enables automatic shipment creation, order data transfer, and delivery status tracking within store business processes. #### [Woocomerce](https://uk.wordpress.org/plugins/nova-post-for-woocommerce/) The official Nova Post plugin for WooCommerce to handle your online store deliveries to 16+ countries. Create orders for address or branch delivery, automatically generate and print waybills, manage statuses, and send tracking numbers to buyers directly from the WooCommerce dashboard.Nova Post API key
How to get the API key 
Tax identification number of the sender's company
API Nova Post parameter: companyTin
Contract ID with Nova Post
API Nova Post parameter: payerContractNumber
Description of the shipment\*
\*To ensure the automatic completion of parcel descriptions, select one of the settings in the Default settings of shipment and printouts section: Product list (Quantity, Name) or Product list (Quantity, SKU, Name, Price)
COD amount\*. If the field is left blank, the parcel will be delivered without COD.
\*To process COD, the Account number for COD (IBAN) and Bank account owner fields must be completed in the module settings.
| Назва | Опис поля |
|---|---|
| serviceCode | Код сервісу, що вказує на наявність послуги «Оплата при отриманні». Завжди "COD" для даного типу оплати. |
| amount | Загальна сума, яку одержувач має сплатити в межах послуги COD. Зазначається двічі:
|
| contractNumber | Якщо існує кілька договорів, необхідно вказати той що потрібно. |
| payerType | Визначає платника послуги, у прикладі це одержувач. |
| currencyCode | Валюта транзакції. Визначається за договором відправника. |
| bankAccountId | Ідентифікаційний податковий номер або еквівалентний ідентифікатор (ЄДРПОУ, ІПН, NIP, IČO). Значення поля CompanyTin відправника юридичної особи. |
| bankAccountName | IBAN |
| commissionPayer | Визначає платника комісії COD: Одержувач/Відправник. |
Визначає платника послуг доставки. Доступні значення:
- Sender,
- Recipient,
- ThirdPerson.
| | payerContractNumber | Номер договору платника для безготівкового розрахунку. | #### Приклад: ``` { "status": "ReadyToShip", "clientOrder": "", "note": "", "payerType": "Sender", "payerContractNumber": "CNPMD-12345678" "invoice": null, "services": [], "parcels": [], "sender": {}, "recipient": {} } ```| Field name | Description |
|---|---|
| serviceCode | Service code indicating that the shipment includes the Cash on Delivery service. Always "COD" for this payment type. |
| amount | The total amount that the recipient must pay within the COD service. It is specified twice:
|
| contractNumber | If multiple contracts exist, the required one must be specified. |
| payerType | Defines the payer of the service; in this example, it is the recipient. |
| currencyCode | Transaction currency. It is determined according to the sender's contract. |
| bankAccountId | Tax identification number or equivalent identifier (EDRPOU, TIN, NIP, IČO). The value corresponds to the sender company's companyTin field. |
| bankAccountName | IBAN |
| commissionPayer | Defines the COD commission payer: Recipient / Sender. |
Defines the payer of delivery services. Available values:
| Region | Number | |
|---|---|---|
| Poland | +48 532 697 974 | wspolpraca@novapost.pl |
| Czech Republic | +420 776 060 379 | sale_cz@novapost.com |
| Germany | +49 170 731 6517 | sale_de@novapost.com |
| Hungary | +36 96 800 609 | support_hu@novapost.com |
| Italy | +39 029 994 0609 | support_it@novapost.com |
| Spain | +34 930 474 609 | support_es@novapost.com |
| Romania | +40 373 785 207 | support_ro@novapost.com |
| Slovakia | +421 552 302 609 | support_sk@novapost.com |
| France | +33 159 420 609 | support_fr@novapost.com |
| Netherlands | +31 203 695 606 | support_nl@novapost.com |
| Great Britain | +44 180 330 0609 | іkhmelevskyi.b@novapost.com |
| Austria | - | support_at@novapost.com |
| Region | Number | |
|---|---|---|
| Baltic region | +37 123 557 979 | balticsales@novapost.com |
| Request Type | Number |
|---|---|
| Partnership Requests | partner_np_europa@novaposhta.ua |