Cross-border shipments from Europe to the USA

This page describes the process of creating shipments from Europe for international delivery to the USA.

Shipment API Interaction Flow

Schema (Object)

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: Draft: The document is in its preliminary stage, not yet finalized. Accepted: Reviewed and accepted, the document is ready for the next steps. Issued: The document has been completed and is ready for shipping. ReadyToShip: Indicates that the shipment is prepared for transport following the creation of the express waybill. Only this value can be specified when creating a shipment. Deleted: The document has been deleted from the system. Returned: The shipment has been returned to its sender. Utilized: Indicates that the physical goods associated with the transportation document have been disposed of or destroyed and the document is closed. Allowed: ReadyToShip
clientOrder	string	yes	Represents all potential order identifiers associated with the shipment. These identifiers are set by the customer for internal tracking purposes and are crucial for tracking the shipment throughout its journey. All entered values can be tracked in the shipment's tracking system. Constraints: Max 50 chars
note	string	yes	Any additional information or special instructions that pertain to the order can be included here. This could encompass delivery instructions, special handling requests, or other pertinent details that facilitate the handling and processing of the shipment. Constraints: Max 255 chars
deliveryType	string	no	Defines the tariff type to be applied to the shipment during creation or update. standard: Standard international delivery tariff. economy: Economy international delivery tariff. express: Express international delivery tariff. If the field is not provided, the tariff type is determined automatically according to current business rules, and the existing shipment creation behaviour remains unchanged.
payerType	enum	yes	Identifies who is responsible for the payment of delivery services. The payer type determines which party bears the cost: Sender: The party sending the goods pays for the delivery. Recipient: The party receiving the goods is responsible for the delivery cost. ThirdPerson: A third party, not the sender or recipient, pays for the delivery services. When selecting ThirdPerson, the field payerContractNumber must be populated with the contract number of the paying party. For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API. This field is also referenced when generating an invoice. Allowed: Sender | Recipient | ThirdPerson
payerContractNumber	string┃null	yes	This field is required in the following cases: When the payerType is set to ThirdPerson. It must contain the payer's contract number. For clients from Ukraine, it is also acceptable to provide the tax identification number (EDRPOU) instead of the contract number. When the payerType is set to Sender or Recipient and a non-cash payment method is used. If this field is not provided in the cases described above, the payment method will automatically default to cash. Ensure that the provided information is accurate, as it is essential for correct payment processing. For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API. Constraints: 2 to 20 chars
services	array	no	Contains information about additional services for the shipment.
services.shipmentParcelRowNumber	integer	yes	Specifies the row number of the parcel to which the service is applied. The value must correspond to the rowNumber of an existing parcel in the parcels array. For services applied to the entire shipment (for example, ExpBackwardGoods), this field must be set to null.
services.serviceCode	string	yes	The code indicating the service. A list of available codes and descriptions of their meanings: COD — The Cash on Delivery (COD) service allows the recipient to pay for the goods directly upon receiving them, without the need for prepayment. The sender can add this service to the shipment, and the recipient has the option to pay for the goods upon delivery and inspect them before making the payment, subject to payment method restrictions established for specific countries. 🔸The COD service is planned to expand to other countries and delivery directions in the future, both for international shipments and within European countries. ExpBackwardGoods — Enables return delivery option for parent shipment ExpBackwardCreditDoc — Enables return delivery of signed documents for domestic document shipments within Moldova. The service is available only for legal entities and only for shipments with the Documents type. The return shipment is created as a separate document delivery (by courier or operator), and the payer is always the Recipient under a non-cash contract. Not available for Parcel Locker and PUDO service channels. In the first iteration, the service is enabled only for selected legal entities. 🔹This field is required for the services group.
services.serviceName	string	yes	Name of the service. Allowed values include: PaymentControl — Payment control service. MoneyTransfer — Money transfer service. Other service types available within the services group. 🔹This field is required within the services group.
services.serviceId	string	yes	Unique identifier (reference ID) of the selected service. This value must correspond to the service reference returned by the system. When creating or updating a shipment, the exact serviceId provided in the service reference response must be copied and used without modification. 🔹This field is required within the services group.
services.amount	number	yes	The total amount the recipient must pay under the COD service. 🔹This field is required for the services group.
services.contractNumber	string┃null	yes	Contract number of the payer responsible for the selected service. This parameter is used to identify the contractual agreement under which the service is paid. The field is required when the service payer is a third party or when non-cash payment terms are applied. If not provided, the payment may be processed according to default billing rules.
services.payerType	string	yes	Determines who is responsible for paying for the service. The payer type determines which party bears the costs: Recipient — The only allowed value for the COD service. Sender, Recipient — Allowed payer values for the ExpBackwardGoods service. Sender, Recipient, ThirdPerson — Allowed payer values for the BackwardDelGoods service. 🔻This field is required
services.additionalParameters	string	yes	Additional parameters for the service.
services.additionalParameters.cod	string	yes	Additional parameters for configuring COD. 🔹These parameters are mandatory and required only for the COD service
services.additionalParameters.cod.bankAccount	object	no	Information describing the bank account details to which the funds will be transferred. Includes the transfer amount, transaction currency, account identifiers, and the party responsible for paying the service fee.
services.additionalParameters.cod.bankAccount.amount	number	yes	The amount that will be transferred to the sender’s account after payment. Specifies the amount the recipient must pay upon receipt. Automatic currency conversion is possible depending on the sender's or recipient's country. 🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
services.additionalParameters.cod.bankAccount.currencyCode	string	yes	The currency for the transaction, defined by the sender’s contract. Specified according to the ISO 4217 standard. 🔸By default, the currency of the sender’s country is used, but it is possible to set the currency manually (Feature under development). Pattern: ^[A-Z]{3}$
services.additionalParameters.cod.bankAccount.bankAccountId	string	yes	Tax identification number of an individual or a legal entity, used for its unique identification in the system and for verifying the existence of an active contract and the availability of financial services. The same as the value passed in the companyTin field. 🔹This field is required for the services.additionalParameters.cod.bankAccount field group. 🔸Must contain the tax identification number or equivalent identifier (EDRPOU, TIN, NIP).
services.additionalParameters.cod.bankAccount.bankAccountName	string	yes	IBAN 🔹This field is required for the services.additionalParameters.cod.bankAccount field group. 🔸Must contain the full account number in IBAN format.
services.additionalParameters.cod.bankAccount.description	string	yes	Additional description of the payment details.
services.additionalParameters.cod.bankAccount.commissionPayer	string	yes	Specifies the party responsible for paying the commission: Recipient Sender 🔹This field is required for the services.additionalParameters.cod.bankAccount field group.
services.additionalParameters.backwardDelivery	object	yes	Additional parameters for configuring return delivery. 🔹These parameters are mandatory and required only for the ExpBackwardGoods service
services.additionalParameters.backwardDelivery.description	string	no	Description of the goods to be returned. This value is used for informational and operational purposes during the return delivery process.
invoice	object	no	This object presents the necessary data for customs authorities to process the consignment efficiently, including the assessment of duties and taxes, and to confirm adherence to import/export regulations. The structured format of the invoice ensures that all pertinent information is easily accessible and clear, facilitating a smoother transit across borders. Updated logic for invoice value handling. Clients must now send only two parameters in the invoice object: cost — total declared value of the invoice currency — currency code of the invoice 🔸It encapsulates the invoice details, which are required for international shipments undergoing customs clearance.
invoice.customerNumber	string┃null	yes	Unique identifier/number of the invoice accompanying the goods in the shipment, generated directly by the client. It is used for customs processing (export and import clearance) because it ensures a clear link between the goods in the shipment and their accompanying documentation, including value, origin, and other necessary information for customs clearance. If a client invoice exists in the shipment but its information is missing—specifically, its number—the shipment processing in the information system will be halted, the customs clearance period will be extended, and in the worst case, customs authorities may refuse clearance and initiate a return to the country of export. 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 invoice.customerNumber field is filled in. Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
invoice.type	string	yes	Type of client invoice accompanying the shipment and used for customs declaration. This field must reflect the actual type of document enclosed in the parcel. Available values: Invoice — commercial invoice for shipments of a commercial nature ProformaInvoice — proforma invoice for shipments of a non-commercial nature 🔹This field is required if the invoice.customerNumber field is filled in. Possible values: Invoice | ProformaInvoice
invoice.incoterm	string	yes	Specifies the trade terms for the shipping agreement between the buyer and seller, based on selected standards from the Incoterms® rules. These terms define the allocation of shipping costs, insurance, customs duties, and the distribution of risk. Only a limited subset of Incoterms® is available for use: DAP (Delivered at Place) - The recipient is responsible for import customs clearance, duties, and taxes. DDP (Delivered Duty Paid) - The sender is responsible for import customs clearance and for paying all applicable duties and taxes. 🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: DAP | DDP
invoice.exportReason	string	yes	Specifies the general reason for exporting items, which is required for customs and other regulatory bodies. This classification helps in understanding the type of shipment without getting into specifics. It's used to categorize shipments at a high level for smoother processing through customs. The available options are: ForPersonalPurposes: Items are for personal use or gifts. Selling: Items are meant for sale. Repair: Items being sent for repair. Return: Items are being returned to the sender or manufacturer. Other: Any reason not covered by the other options. 🔹This field is required for shipments crossing the EU border or going outside the EU. Possible values: ForPersonalPurposes,Selling,Repair,Return,Other
invoice.exportReasonId	integer	yes	Specifies the identifier of the export reason, which is required for customs and other regulatory bodies. Possible values: 1
invoice.cost	number	yes	Total declared invoice value in the original currency, which must equal the sum of all invoice items calculated as (amount × cost) for each item. Used for customs and shipment declarations. 🔸If the provided cost value does not equal the sum of the cost values in the items array, it will be automatically recalculated by the system on our side. 🔸Values are validated for decimal precision, and digits beyond two decimal places are ignored. 🔹This field is required for shipments crossing the EU border or going outside the EU. 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: Sender: The party sending the goods pays for the customs duties. Recipient: The party receiving the goods is responsible for the customs duties costs. ThirdPerson: A third party can only pay for customs services if this is permitted and the payer for delivery services is also a third party. The default value is "Recipient". This value will also be applied automatically if the parcel exceeds the maximum allowed value (in the recipient country’s currency) for which the sender is permitted to pay customs duties. 🔹This parameter is required and valid only for the UA-EU direction. Possible values: Sender | Recipient | ThirdPerson
invoice.items	object	yes	A detailed list of goods being shipped, including required descriptions and values, essential for customs declarations and assessing duties. Logic: If the items block is provided, the system checks whether the total sum of all (items.cost × items.amount) matches the invoice.cost value. If not — the system updates invoice.cost to equal the sum of all items. 🔸It is required to provide this information for each individual good in the shipment in the form of an array.
invoice.items.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 hsCode from the Cargo Classifiers (UKT ZED) dictionary. Validation rules: If the sender or recipient country is Moldova (MD) or Canada (CA): The hsCode must consist of exactly 10 numeric characters. If the input is longer than 10 digits, it will be truncated on the right. If it contains fewer than 10 digits - validation error. For all other countries: The hsCode must contain between 8 and 10 numeric characters (inclusive). If fewer than 8 digits – validation error. All non-digit characters will be stripped automatically before validation. If the value of the hsCode field is 210690 or 630900, the following conditions must be met: The measurementCode must be set to kg. Each item with this hsCode must be unique — the invoice must not contain more than one item with code 210690 or 630900. The amount value must not exceed 10. 🔹This field is required for shipments crossing the EU border or going outside the EU. Constraints: Max 255 chars
invoice.items.id	string | null	no	Unique identifier of the invoice item.
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 name field, this parameter also supports Unicode encoding. Using the \uXXXX format, it accommodates the accurate rendering of any special characters necessary for the correct representation of the item's name in English. 🔹This field is required for shipments crossing the EU border or going outside the EU. 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.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 30 chars
invoice.items.producerAndModel	string | null	no	The parameter represents the manufacturer and model of the device when creating a shipment. Both values are included in a single parameter. This parameter is mandatory for the following categories: Electrical appliances Laptops Phones Large and small household appliances Other similar items 🔸This field is not required; however, shipments with this field filled are given priority during customs clearance. 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 invoice.items array is present in the request. The system validates that the sum of actualWeight values across all invoice items matches the total shipment weight (sum of parcels[].actualWeight). ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. 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 measurementCode. 🔹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: parcel: Small to medium-sized packages, typically for consumer goods and retail items. documents: Postal shipments containing documents such as letters, contracts, and official papers. This category is specifically for items that weigh no more than 1 kg and have dimensions not exceeding 35 cm in length, 25 cm in width, and 2 cm in height. pallet: Type of cargo formed as a pallet shipment with fixed dimensions and weight limits, available in the Business Cabinet of Europe for legal entities: Up to 250 kg, area ~0.48 m², dimensions 80 × 60 × 170 cm Up to 500 kg, area ~0.96 m², dimensions 120 × 80 × 170 cm Up to 750 kg, area ~1.2 m², dimensions 120 × 100 × 170 cm Up to 1000 kg, area ~1.2 m², dimensions 120 × 100 × 170 cm Possible values: parcel | documents | pallet
parcels.number	string	no	Transportation document number assigned to the parcel.
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: If insuranceCurrencyCode is not provided, the value must be specified in the currency of the sender's country. If insuranceCurrencyCode is provided, the value can be specified in any supported currency (ISO 4217). The system will automatically convert it to the sender's country currency before further processing. 🔸When insuranceCurrencyCode is used, all parcels must specify the same currency code. Mixed or partially filled currency values will result in a validation error. The value must always be greater than 0, regardless of the shipment direction." Example: 1.5
parcels.insuranceCurrencyCode	string	no	ISO 4217 currency code for the declared insurance value (insuranceCost). When provided, the system converts insuranceCost to the sender's country currency automatically. If used, all parcels must have the same insuranceCurrencyCode. 🔹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 invoice.items array is present in the request. The system validates that the sum of actualWeight values across all invoice items matches the total shipment weight (sum of parcels[].actualWeight). ⚠️IMPORTANT: Ensure that all invoice item weights are correctly rounded and that their total weight exactly matches the shipment weight to avoid validation errors. Constraints: Min 1┃Max 2147483647
parcels.volumetricWeight	integer	yes	Volumetric weight of the parcel.
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: The sender's phone number must be valid and reachable in case of delivery issues. If the number is submitted in a local (non-international) format, the system will attempt to normalize it, but such logic is limited and may not support all variations across countries. We strongly recommend implementing front-end validation to ensure numbers are entered in the correct international format. 🔻This field is required
sender.email	string	yes	Email address of the sender, providing an electronic means of contact for updates, inquiries, and important notifications about the shipment. 🔹This field is required for shipments crossing the EU border or going outside the EU.
sender.name	string	yes	The full name of the individual sender or the primary contact person for a company sender. This name is used in all correspondences and documents related to the shipment. 🔸Important for EU → UA international shipments: The sender name must be provided using Latin characters only. Use of Cyrillic characters (including Ukrainian letters) is not allowed and will result in validation or processing errors on the Last Mile partner side. 🔻This field is required 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 sender.addressParts group and the sender.divisionId field are missing or empty Example: 32521/1
sender.divisionId	integer | null	yes	Division ID for specific branch identification. 🔹This field is required if both the sender.addressParts group and the sender.divisionNumber field are missing or empty 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 sender.divisionNumber and sender.divisionId fields are missing or empty. 🔸For shipments where the sender country is Moldova or Ukraine, the sender city is validated against internal settlement directories. If the settlement cannot be resolved due to an invalid or unmapped value, the shipment will not be created. 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 sender.divisionNumber and sender.divisionId fields are missing or empty. 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 sender.divisionNumber and sender.divisionId fields are missing or empty. 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 sender.divisionNumber and sender.divisionId fields are missing or empty. 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: Non-excise goods: The EORI code is not mandatory if non-excise goods are being shipped from Ukraine to a legal entity in Europe. If the recipient does not have an EORI code, one will be automatically assigned. Excise goods: The EORI code is required for shipments of excise goods. The recipient must obtain an EORI code before the goods can be shipped. 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: For deliveries to Nova Post branches in Europe, Ukrainian mobile numbers are acceptable. For deliveries to partner locations (such as InPost, GLS, Venipak, Cargus, etc.) and cross-border address deliveries, the phone number must belong to a mobile operator in the recipient's country. If the phone number is submitted in a local (non-international) format, the system will attempt to normalize it to the international format, but the internal algorithm does not cover all possible cases. If your system does not support front-end validation of phone numbers, we recommend informing us about failed phone number cases so we can assess potential improvements to the normalization logic. 🔻This field is required
recipient.email	string	yes	The email address of the recipient, serving as a digital contact point for shipment updates, inquiries, and essential notifications. 🔹This field is required for shipments crossing the EU border or going outside the EU.
recipient.name	string	yes	The complete name of the individual recipient or the primary contact for a company recipient. This is the name used for all shipping-related correspondence and documentation. 🔻This field is required 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 recipient.addressParts group and the recipient.divisionId field are missing or empty Example: 32521/1
recipient.divisionId	integer | null	yes	Division ID for specific branch identification. 🔹This field is required if both the recipient.addressParts group and the recipient.divisionNumber field are missing or empty 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 recipient.divisionNumber and recipient.divisionId fields are missing or empty. 🔸For shipments where the recipient country is Moldova or Ukraine, the recipient city is validated against internal settlement directories. If the settlement cannot be resolved due to an invalid or unmapped value, the request will be rejected with the error:validation.condition.recipient_settlement_not_defined. 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 recipient.divisionNumber and recipient.divisionId fields are missing or empty. 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 recipient.divisionNumber and recipient.divisionId fields are missing or empty. 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 recipient.divisionNumber and recipient.divisionId fields are missing or empty. 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

Create Shipment

post

/shipments

Authorizations

AuthorizationstringRequired

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

Body

statusstring · enumOptional

Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle.

Possible values:

clientOrderstring · max: 50Optional

Represents all potential order identifiers associated with the shipment.

notestring · max: 255Optional

Any additional information or special instructions that pertain to the order can be included here.

deliveryTypestringOptional

Defines the tariff type to be applied to the shipment during creation or update.

payerType*string · enumOptional

Identifies who is responsible for the payment of delivery services.

Possible values:

payerContractNumberstring · min: 2 · max: 20 · nullableOptional

Required for ThirdPerson payments and for non-cash payments when payerType is Sender or Recipient.

Responses

201

Successfully created shipment.

application/json

idinteger · min: 1Optional

A unique identifier assigned to each shipment, facilitating internal operations such as modifications, system searches, and deletion of shipments. The id serves as a key reference for administrative and logistical processes within the delivery system, allowing precise access and management of shipment records.

numberstringOptional

The transportation document number provided to clients for tracking purposes and accessing printed forms. It also facilitates shipment searches within the system, offering a customer-friendly way to monitor shipment progress. While number is used externally for tracking and documentation, it can also serve internal needs similar to id for identifying shipments in certain system operations.

Pattern: ^[A-Z]{4}\d{10}$

scheduledDeliveryDatestring · date-time · nullableOptional

Estimated delivery date based on routing and service level, subject to change based on logistics and external factors. Date in ISO 8601 format.

Example: 2023-04-14T09:00:00Z

statusstringOptional

Current status of the shipment. Initially set to ReadyToShip upon creation, indicating it's prepared for dispatch.

costnumber · floatOptional

Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.

Example: 31.5

parcelsAmountinteger · min: 1Optional

The total number of parcels included in the shipment. This count helps in logistics planning and tracking.

createdAtstring · date-timeOptional

The date-time when the shipment record was created in the system. Date in ISO 8601 format.

Example: 2023-04-11T10:42:05Z

updatedAtstring · date-timeOptional

The last date-time when the shipment record was updated. Helps in tracking changes and updates made to the shipment details.Date in ISO 8601 format.

Example: 2023-04-11T10:42:05Z

deletedAtstring · date-time · nullableOptional

The date-time when the shipment was canceled or removed from the system. If not canceled, this field is null.

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

post/shipments

POST /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1018

{
  "status": "ReadyToShip",
  "clientOrder": "",
  "note": "",
  "payerType": "Sender",
  "invoice": {
    "incoterm": "DAP",
    "exportReason": "Selling",
    "cost": 80,
    "currency": "USD",
    "items": [
      {
        "amount": 1,
        "measurementCode": "pieces",
        "cost": 80,
        "actualWeight": 300,
        "name": "Convertible roof hydraulic pump",
        "nameEng": "Convertible roof hydraulic pump",
        "hsCode": "8413602000",
        "id": null,
        "madeInCountryCode": null,
        "serialNumber": null,
        "material": null,
        "materialEng": null
      }
    ],
    "customerNumber": null,
    "customerCreatedAt": null,
    "type": null,
    "payerFeesCustoms": null
  },
  "services": [],
  "parcels": [
    {
      "cargoCategory": "parcel",
      "number": null,
      "parcelDescription": "parcel for test",
      "insuranceCost": 100,
      "rowNumber": 1,
      "width": 200,
      "length": 350,
      "height": 100,
      "actualWeight": 300,
      "volumetricWeight": 300
    }
  ],
  "sender": {
    "companyTin": "",
    "companyName": "",
    "phone": "380007654321",
    "email": "[e-mail]",
    "name": "Maks Tester",
    "countryCode": "PL",
    "divisionId": 1,
    "ioss": null
  },
  "recipient": {
    "phone": "12125551234",
    "email": "[e-mail]",
    "name": "Chuck Norris",
    "countryCode": "US",
    "divisionId": 2138547
  }
}

{
  "id": 4673662,
  "number": "SHPL2643850049",
  "scheduledDeliveryDate": "2026-10-05T22:00:00.000000Z",
  "status": "ReadyToShip",
  "cost": 180,
  "parcelsAmount": 1,
  "createdAt": "2026-09-21T09:36:05.284005Z",
  "updatedAt": "2026-09-21T09:36:05.284005Z",
  "deletedAt": null,
  "recipientsArea": null,
  "recipientsAreaNumber": null,
  "deliveryPartners": [
    {
      "id": 3678025,
      "shipmentId": 4673662,
      "type": "LastMile",
      "name": "UPS",
      "number": "1ZXXXXXXXXXXXXXXXX",
      "main": true,
      "parcelNumber": null,
      "createdAt": "2026-09-21T09:36:05.284005Z",
      "updatedAt": "2026-09-21T09:36:05.284005Z",
      "deletedAt": null,
      "flags": [
        "Shipment",
        "Deletion",
        "Marking"
      ],
      "routeId": null,
      "divisionId": 1935309,
      "countryCode": "PL",
      "status": "Created"
    },
    {
      "id": 3678026,
      "shipmentId": 4673662,
      "type": "LastMile",
      "name": "UPS",
      "number": "1ZXXXXXXXXXXXXXXXX",
      "main": false,
      "parcelNumber": "SHPL2643850049",
      "createdAt": "2026-09-21T09:36:05.284005Z",
      "updatedAt": "2026-09-21T09:36:05.284005Z",
      "deletedAt": null,
      "flags": [
        "Tracking",
        "Scanning"
      ],
      "routeId": null,
      "divisionId": 1935309,
      "countryCode": "PL",
      "status": "Created"
    }
  ],
  "services": [
    {
      "id": "20441618",
      "shipmentId": "4673662",
      "shipmentParcelRowNumber": null,
      "serviceId": "5637144609",
      "serviceName": "Insurance",
      "amount": 100,
      "contractNumber": null,
      "payerType": "Sender",
      "paymentStatus": "FreeOfCharge",
      "divisionId": null,
      "price": 0,
      "discount": 0,
      "cost": 0,
      "currencyCode": "PLN",
      "user": "4ec5890f-d49f-4ce1-ae35-98c41f03910c",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "countryCode": null,
        "divisionId": null,
        "addressParts": null,
        "cod": null,
        "backwardDelivery": null,
        "partner": null,
        "codPaymentService": null,
        "sameDay": null,
        "longStorageDays": null,
        "recipientPhoneAlternative": null,
        "quantity": null,
        "actionType": null,
        "restrictions": null,
        "payerType": null,
        "thirdPerson": null,
        "multipleReturns": null,
        "hybridPayment": null,
        "processOption": null,
        "consolidationMerchantTin": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "createdAt": "2026-09-21T09:36:05.284005Z",
      "updatedAt": "2026-09-21T09:36:05.284005Z"
    },
    {
      "id": "20441619",
      "shipmentId": "4673662",
      "shipmentParcelRowNumber": null,
      "serviceId": "5640076500",
      "serviceName": "CustomsBrokerageDEST",
      "amount": 100,
      "contractNumber": null,
      "payerType": "Sender",
      "paymentStatus": "FreeOfCharge",
      "divisionId": null,
      "price": 0,
      "discount": 0,
      "cost": 0,
      "currencyCode": "PLN",
      "user": "4ec5890f-d49f-4ce1-ae35-98c41f03910c",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "countryCode": null,
        "divisionId": null,
        "addressParts": null,
        "cod": null,
        "backwardDelivery": null,
        "partner": null,
        "codPaymentService": null,
        "sameDay": null,
        "longStorageDays": null,
        "recipientPhoneAlternative": null,
        "quantity": null,
        "actionType": null,
        "restrictions": null,
        "payerType": null,
        "thirdPerson": null,
        "multipleReturns": null,
        "hybridPayment": null,
        "processOption": null,
        "consolidationMerchantTin": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "createdAt": "2026-09-21T09:36:05.284005Z",
      "updatedAt": "2026-09-21T09:36:05.284005Z"
    },
    {
      "id": "20441620",
      "shipmentId": "4673662",
      "shipmentParcelRowNumber": "1",
      "serviceId": "5637144588",
      "serviceName": "InternationalParcelS",
      "amount": 1,
      "contractNumber": null,
      "payerType": "Sender",
      "paymentStatus": "NeedPay",
      "divisionId": null,
      "price": 180,
      "discount": 0,
      "cost": 180,
      "currencyCode": "PLN",
      "user": "4ec5890f-d49f-4ce1-ae35-98c41f03910c",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "countryCode": null,
        "divisionId": null,
        "addressParts": null,
        "cod": null,
        "backwardDelivery": null,
        "partner": null,
        "codPaymentService": null,
        "sameDay": null,
        "longStorageDays": null,
        "recipientPhoneAlternative": null,
        "quantity": null,
        "actionType": null,
        "restrictions": null,
        "payerType": null,
        "thirdPerson": null,
        "multipleReturns": null,
        "hybridPayment": null,
        "processOption": null,
        "consolidationMerchantTin": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "createdAt": "2026-09-21T09:36:05.284005Z",
      "updatedAt": "2026-09-21T09:36:05.284005Z"
    }
  ],
  "parcels": [
    {
      "number": "SHPL2643850049",
      "rowNumber": 1,
      "untied": false,
      "pricingType": "parcel",
      "cargoCategory": null,
      "cargoCategoryId": 2,
      "parcelDescription": "parcel for test",
      "insuranceCost": 100,
      "length": 350,
      "width": 200,
      "height": 100,
      "actualWeight": 300,
      "volumetricWeight": 1750,
      "recipient": null,
      "clientParcel": null
    }
  ]
}