Novaposhta

Get counterparties list filtered by property (Sender/Recipient/ThirdPerson) via Counterparty/getCounterparties (doc 1.6). Docs require an API key, recommend caching the directory daily, and note each page tops out at 500 rows so always filter with CounterpartyProperty/FindByString.

Get counterparty options and permissions via Counterparty/getCounterpartyOptions (doc 1.23) to see booleans such as CanPayTheThirdPerson, CanSameDayDelivery, HideDeliveryCost, etc., before building a waybill.

Create new counterparty (private person or organization) with Counterparty/save (docs 1.20–1.21). Provide CityRef + CounterpartyProperty/Type; private persons require first/last name while organizations must also send OwnershipForm and EDRPOU. Docs recommend refreshing supporting directories monthly and note an API key is required.

Update existing counterparty details via Counterparty/update (doc 1.22). Nova Poshta only lets you edit a counterparty from creation up until you create a waybill (ІД) with it, so run updates early.

List documents created in the given date range. Per doc 1.2, these queries target the InternetDocument model used for оформлення відправлень, so date filters help keep the success/data/errors response manageable.

Get movement history for up to 10 documents including statuses and timestamps. Doc 1.2 identifies InternetDocument numbers as the primary shipment identifiers, which this endpoint accepts in batches.

Decode Nova Poshta API message code into human readable text. Doc 1.2 explains how every response contains success/data/errors/warnings/info blocks with numeric codes; this helper calls getMessageCodeText to map those codes to UA/RU descriptions.

List backward delivery cargo types via Common/getBackwardDeliveryCargoTypes (doc 1.18). Returns types of cargo that can be sent back (documents, money, etc.). Used for return shipments and COD. Docs recommend caching monthly.

List cargo descriptions with optional search via Common/getCargoDescriptionList (doc 1.15). Returns predefined descriptions for common cargo types. Supports search by keyword. Docs recommend caching monthly.

List available cargo types supported by Nova Poshta via Common/getCargoTypes (doc 1.8). Docs advise caching this API-key-protected directory monthly; expect values such as Parcel, Cargo, Documents, TiresWheels, Pallet.

List corporate ownership forms required for counterparty creation via Common/getOwnershipFormsList (doc 1.11). Docs provide both short and full names for refs such as ТОВ, ПрАТ, ФГ and recommend a monthly refresh.

List available packaging types via Common/getPackList (doc 1.10). Returns standard package dimensions and descriptions. Useful for calculating delivery costs and validating package options. Docs recommend caching monthly.

List pallet types with dimensions and weight via Common/getPalletsList (doc 1.13). Refresh monthly per docs, especially when offering reverse delivery of pallets.

Get list of payment forms (Cash/NonCash) for waybill creation with Common/getPaymentForm (doc 1.7). Nova Poshta notes non-cash payments are available only to contracted clients, so keep a cached copy to validate user choices.

List supported payment methods for shipments (Cash/NonCash) matching the Common/getPaymentForm directory from doc 1.7, which notes that non-cash payments are only available to customers with a Nova Poshta contract.

Get available pickup time intervals via Common/getPickupTimeIntervals (doc 1.17). Returns time windows when Nova Poshta can pick up packages from sender. Requires city reference and date. Docs recommend caching hourly.

List payer types for redelivery via Common/getTypesOfPayersForRedelivery (doc 1.19). Returns who can pay for backward delivery (Sender/Recipient). Used with return shipments. Docs recommend caching monthly.

List delivery service types through Common/getServiceType (doc 1.9). Includes WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors, DoorsPostomat, and WarehousePostomat. Docs recommend refreshing this directory monthly.

Get available delivery time intervals for recipient city using Common/getTimeIntervals (doc 1.16). Requires RecipientCityRef (and optional DateTime) and returns Number/Start/End entries that docs recommend caching monthly.

List available tires and wheels types via Common/getTiresWheelsList (doc 1.12). Returns types and descriptions for shipping tires and wheels as cargo. Docs recommend caching monthly.

Get list of counterparty types (PrivatePerson/Organization) via Common/getTypesOfCounterparties (doc 1.14). Requires API key and, per docs, should be refreshed monthly to stay aligned with sender/recipient onboarding rules.

Get list of payer types (Sender/Recipient/ThirdPerson) for waybill creation via Common/getTypesOfPayers (doc 1.7). Docs stress the ThirdPerson payer is accessible only after signing a service contract and that the directory should be cached monthly.

Track a single Nova Poshta document by number and optional phone to receive live status, location, and ETA. Doc 1.2 describes the standard success/data/errors/warnings/info envelope returned by Nova Poshta, which this helper surfaces back to the caller.

Track multiple Nova Poshta documents with organized results and statistics via TrackingDocument/getStatusDocuments (doc 1.2). Returns successful/failed tracking attempts with delivery statistics (delivered, in-transit, at-warehouse counts). More convenient than track_multiple_documents for batch operations.

Track multiple Nova Poshta documents at once and receive aggregated statistics. Doc 1.2 states every API call returns the same envelope, so use the success/errors/warnings fields here to mirror the native batch tracking response.

Calculate delivery cost and optional delivery date estimation for a shipment. Doc 1.2 explains that every Nova Poshta call sends apiKey/modelName/calledMethod/methodProperties, so this helper either forwards your raw InternetDocument payload or builds one from typed fields (CitySender, CityRecipient, ServiceType, CargoType, Cost, Weight, SeatsAmount).

Create a standard Nova Poshta waybill via InternetDocument/save. For sending FROM a postomat, pass the postomat Ref as SenderAddress, use WarehouseWarehouse or WarehouseDoors, and provide lower camel case OptionsSeat fields. For delivery TO a postomat use waybill_create_to_postomat.

Batch create multiple waybills sequentially via InternetDocument/save (doc 1.2). Processes each waybill one by one to avoid rate limiting. Returns array of results including any errors. Useful for bulk shipment creation.

Deprecated compatibility alias for waybill_create_to_postomat. Creates a waybill for delivery TO a recipient postomat.

Create a waybill for delivery TO a recipient postomat via InternetDocument/save, using ServiceType DoorsPostomat or WarehousePostomat. OptionsSeat uses lower camel case fields such as weight and volumetricWidth.

Create a Nova Poshta waybill with additional options and services via InternetDocument/save (doc 1.2). Supports backward delivery, additional services, third-party payer, and RedBox barcodes. Use this when you need COD, insurance, or return shipments.

Delete one or multiple waybills by their DocumentRef via InternetDocument/delete (doc 1.2). Waybills can only be deleted before they enter processing. Returns success/error status for the operation.

Batch delete multiple waybills by their DocumentRef via InternetDocument/delete (doc 1.2). Alias for waybill_delete that processes all refs in a single API call. Waybills can only be deleted before they enter processing.

Get estimated delivery date for a city pair and service type. Doc 1.2 outlines the generic Nova Poshta envelope, and this helper builds the methodProperties (CitySender, CityRecipient, ServiceType, optional DateTime) expected by the delivery-date method.

Get complete shipment estimate (price + delivery date) in one call via InternetDocument/getDocumentPrice and getDocumentDeliveryDate (doc 1.2). Combines cost calculation and delivery date estimation for convenience. Requires the same PascalCase parameters as waybill_calculate_cost.

Update an existing waybill. Per doc 1.2 the same InternetDocument request envelope is used for update calls, so pass the raw payload (must include DocumentRef) exactly as defined by Nova Poshta.