--- title: "Find Shipments List" method: GET path: "/shipments" tags: ["Shipments"] --- # Find Shipments List `GET /shipments` This API method enables you to retrieve a list of transportation documents (shipments) that you have created. By making a request with this method, you can access the transportation documents that belongs to you or your account. The response will include details of each shipment, such as the shipment ID, number, recipient, cargo detail, and other relevant information. ## Query parameters - `numbers[]` string - `ids[]` integer - `limit` integer - `page` integer - `inRegistry` boolean - `registerNumber` string - `senderDivisionId` integer ## Response `200` shipments - object - `current_page` integer — Current page. - `last_page` integer — Total pages found. - `per_page` integer — Current objects` limit for a single page. - `total` integer — Total objects found. - `from` integer, nullable - `to` integer, nullable - `items` object[] — Items` information in the invoice. - `id` string — 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. - `version` integer — Version of the document, each change of the document is +1. - `number` string — Transportation document number. - `dateTime` string — Document creation datetime. - `scheduledDeliveryDate` string, nullable — Scheduled delivery date. - `closingDate` string, nullable — Document closing date. Displayed after successful delivery. - `createdAt` string — Datetime of creation. - `updatedAt` string — Datetime of update. - `deletedAt` string, nullable — Datetime if removed, otherwise is null. - `userCreate` string — Internal data, not for use. - `status` string — The actual status of the document (e.g. `ReadyToShip`, `Accepted`, `Issued`, `Draft`, `Deleted`). - `gtid` string — Internal data, not for use. - `paymentStatus` string — Status of payment for delivery services (e.g. `Paid`, `NeedPay`, `ContractAfterPayment`). - `currencyCode` string — Currency code according to the conditions of the payer contract, according to iso-4217 standard. - `parcelsAmount` integer — Amount of objects in parcels. - `clientOrder` string — 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. - `note` string — 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. - `payerType` string — Information about who pays for delivery (e.g. `Sender`, `Recipient`, `ThirdPerson`). - `payerContractId` integer, nullable — ID number of a person or organization that pays for delivery. - `payerContractNumber` string, nullable — Contains the contract number if `payerType` is set to `ThirdPerson`. Also this field can can contain the contract number of a sender as the payer when non-cash transactions are used. - `postomatCellReservation` string — Internal data, not for use. - `postomatOrderRef` string — Internal data, not for use. - `firstDayStorage` string, nullable — Start date of shipment storage. - `cargoAutoReturnDate` string, nullable — Date of automatic return of the shipment, if the service is ordered. - `marketplacePartner` string — Internal data, not for use. - `registerNumber` string — Internal data, not for use. - `customerNote` string — Internal data, not for use. - `creationDateNote` string — Internal data, not for use. - `sender` object — Information about the sender. Parameter contains a few variables to describe person or organization who sending cargo (cargo owner). - `companyId` integer, nullable — Internal data, not for use. - `companyTin` string — The tax identification number (TIN) of a legal entity. 🔹**Empty parameter if sender not a company.** - `companyName` string — Company name, in case the sender is a legal entity. - `phone` string — 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. - `email` string — Sender`s E-mail. - `name` string — Contact person. - `countryCode` string — Sender's country code, according to the ISO 3166-1 Alpha-2 standard. For example, PL. - `settlementId` string — Settlement id code. - `cityId` integer, nullable — City id code. - `address` string — Home address or warehouse description. - `addressParts` object — Sender's address in case of sending from the address. Parameter contains a few variables to describe sender`s pick up address or other place beside warehouses. - `postCode` string — Postal code. Symbols that specifies address for a proper sort of cargo, only for address delivery. - `region` string — City region name, only for address delivery. Proper name can be used from settlement request. - `city` string — City or town name, only for address delivery. Proper name can be used from settlement request. - `street` string — Street name, only for address delivery. - `building` string — Building number, only for address delivery. - `block` string — Block. - `flat` string — Apartment number, only for address delivery. - `note` string — Additional information about sender`s address. - `divisionId` string — Warehouse`s id code. If sending with warehouse, than this parameter must contain information. - `divisionCategory` string — Warehouse type. - `archive` boolean — Internal data, not for use. - `recipient` object — Information about the recipient. Parameter contains a few variables to describe person or organization who must receive cargo. - `companyId` integer, nullable — Internal data, not for use. - `companyTin` string — The tax identification number (TIN) of a legal entity. 🔹**Empty parameter if recipient not a company.** - `companyName` string — Company name, in case the sender is a legal entity. - `phone` string — 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. - `email` string — Recipient`s E-mail. - `name` string — Surname and first name of the recipient or representative of the company, if it is a legal entity. - `countryCode` string — Recipient's country code, according to the ISO 3166-1 Alpha-2 standard. For example, UA. - `settlementId` string — Settlement id code. - `cityId` integer, nullable — City id code. - `address` string — Home address or warehouse description. - `addressParts` object — Recipient's address in case of sending to the address. Parameter contains a few variables to describe recipient`s delivery address or other place beside warehouses. - `postCode` string — Postal code. - `region` string — City region name, only for address delivery. - `city` string — City or town name, only for address delivery. - `street` string — Street name, only for address delivery. - `building` string — Building number, only for address delivery. - `block` string — Block. - `flat` string — Apartment number, only for address delivery. - `note` string — Additional information about sender`s address. - `divisionId` string — Warehouse`s id code. If receiving with warehouse, than this parameter must contain information. - `divisionCategory` string — Warehouse type. - `archive` boolean — Internal data, not for use. - `parcels` object[] — Parcels` description block. Array contains objects, each object responsible for information about parcel. - `number` string — Transportation document number. - `row_number` integer — Parcel number. - `untied` boolean — Internal data, not for use. - `cargo_category_id` string — Internal data, not for use. - `cargo_category_group` string — Parcel type. - `parcel_description` string — A brief description of the contents of the package. - `insurance_cost` number — The amount of the declared value. - `length` integer — The actual length of the parcel in mm. - `width` integer — The actual width of the parcel in mm. - `height` integer — The actual height of the parcel in mm. - `actual_weight` integer — The actual weight of the parcel in grams. - `volumetric_weight` integer — The volumetric weight of the parcel. - `length_check` integer, nullable - `width_check` integer, nullable - `height_check` integer, nullable - `actual_weight_check` integer, nullable - `volumetric_weight_check` integer, nullable - `services` object[] — Information about international shipping. - `id` integer — Unique identifier. Internal data, not for use. - `service_id` string — Service`s identifier. Internal data, not for use. - `service_type` string — Type of service (e.g. `InternationalServices`, `MainService`, `AdditionalServices`). - `service_name` string — Name of the service that is part of the shipment cost. Example: `Parcel international delivery (medium)`, `Parcel from home`. This field represents one of the individual services that together form the total delivery cost. The response may include several such services depending on the selected delivery options and shipment configuration. To obtain the full list of possible services and understand which combinations may apply, please contact your account manager. - `parcel_number` string — Position number in the transportation document. - `payer_type` string — Information about who pays for delivery (e.g. `Sender`, `Recipient`, `ThirdPerson`). - `amount` number — Number of objects in the position. - `price` number - `discount` number - `cost` number - `cost_before_check` number, nullable - `payment_status` string — Status of payment for delivery services (e.g. `Paid`, `NeedPay`, `ContractAfterPayment`, `FreeOfCharge`, `Holded`). - `additional_parameters` object - `cod` integer, nullable — Money`s transfer information. - `date` integer, nullable - `from` integer, nullable - `to` integer, nullable - `string` integer, nullable - `fullName` integer, nullable - `phone` integer, nullable - `onlineTracking` object — General statuses of the package movement (created/on the way/arrived/received). Types of statuses are displayed, into which detailed statuses are grouped. - `tracking_status_code` integer — Tracking status code. - `tracking_update_date` string — Tracking update date. - `short_description` string — Tracking short status description. - `long_description` string — Tracking full status description. - `info` string - `label` string - `tracking` unknown[] — Array of statuses representing all stages of the parcel's journey from the sender to the recipient with detailed information. - unknown - `totalWeight` integer — Document total weight. - `totalInsuranceCost` number — Document total declared cost. The value must greater than zero. - `totalCost` number — Cost for delivery services. The value must greater than zero. - `invoice` object — Invoice data used for customs processing, including declared value, currency, and goods information. The structure of the invoice object in the response depends on the data provided during shipment creation. 🔹If some fields were not provided in the request, they may be absent in the response. - `customerNumber` string, nullable — Unique identifier/number of the invoice accompanying the goods in the shipment, generated by the client. Used for customs processing to link shipment goods with accompanying documentation. - `customerCreatedAt` string, date-time — Date specified in the invoice accompanying the shipment. - `type` string — Type of client invoice accompanying the shipment and used for customs declaration. - `incoterm` string — Specifies the trade terms for the shipping agreement between the buyer and seller, based on selected standards from the Incoterms® rules. - `exportReason` string — Specifies the general reason for exporting items. - `cost` number — Total declared invoice value in the original currency. - `currency` string — ISO 4217 currency code of the invoice. - `payerFeesCustoms` string — Specifies who is responsible for paying for customs services. - `items` object[] — A detailed list of goods being shipped. 🔹Objects may include only the fields provided during shipment creation. Optional fields may be absent in the response. - `customerId` string — Client item identifier. - `hsCode` string — The Harmonized System code for each item. - `name` string — Item name in the original language used for customs identification. - `nameEng` string — Item name in English for international processing and documentation. - `material` string — Primary material of the item. - `materialEng` string — Material description in English. - `madeInCountryCode` string, nullable — Country of origin code (ISO 3166-1 alpha-2). - `producerAndModel` string — Manufacturer and model of the item. - `actualWeight` integer — Total weight of all units of the item in grams. - `measurementCode` string — Unit of measurement (e.g. pieces, kg). - `amount` number — Quantity of the item in the specified unit. - `cost` number — Value per unit of the item in the sender’s currency. ## Other responses - `401` — Unauthorized - `404` — The specified resource was not found - `422` — Validation error - `503` — Connection time-out --- [API](https://skmtc.net/novapost/apis/api-nova-post.md) · [All operations](https://skmtc.net/novapost/apis/api-nova-post/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novapost/api-nova-post/revisions/60e380005037/schema)