novaposhta

Delete counterparty address by reference using Address/delete (doc 1.25). Allowed only before the address participates in an Internet document; afterward the API blocks deletion.

Get settlement country regions (регіонів) for a specific area via Address/getSettlementCountryRegion (doc 1.3). Returns list of regions within an administrative area. Requires areaRef parameter. Docs recommend caching for 12 hours.

Get settlement areas (областей) via Address/getSettlementAreas (doc 1.3). Returns list of administrative regions/areas in Ukraine. Docs recommend caching this public directory for 12 hours.

List Nova Poshta warehouses (branches, postomats, pickup points) via Address/getWarehouses (doc 1.5). Docs emphasize caching the branch directory daily to leverage schedule arrays, max weight limits, and warehouse types without re-fetching thousands of rows. IMPORTANT: Always use limit parameter (recommended: 10-20) to avoid large responses.

Create new address for a counterparty via Address/save (doc 1.24). Requires API key plus CounterpartyRef, StreetRef, BuildingNumber; response returns the Ref and Description needed for door-to-door delivery.

Find Nova Poshta cities by name or postal index using Address/getCities (doc 1.3). Docs note the city directory is public (no API key) but must be cached and refreshed daily because it exposes Area and Delivery1-Delivery7 flags. IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

Search for settlements (city, town, village) with pagination over the same Address/getCities dataset described in doc 1.3 (Area + Delivery1-Delivery7 fields, daily refresh recommended). IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

Search for streets inside a settlement via Address/getStreet (doc 1.4). Used for door pickup/delivery flows, limited to 500 records per page, public but should be cached and refreshed daily. IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

Update existing counterparty address with Address/update (doc 1.25). Nova Poshta docs stress you can edit an address only until a waybill is created with it, so run this immediately after address creation.

Delete contact person by reference using ContactPerson/delete (doc 1.27). Nova Poshta allows deletions via API only for legal entities and only until the contact was used on an Internet document.

Create new contact person for a counterparty via ContactPerson/save (doc 1.26). Docs require entering all fields in Ukrainian and with an API key; response returns the Ref/Description pair referenced in waybills.

Update existing contact person details via ContactPerson/update (doc 1.27). Only legal entities may edit full profiles, private persons can change phone only, and edits are allowed solely before a waybill is issued for that counterparty.

Delete counterparty by reference using Counterparty/delete (doc 1.22). IMPORTANT: Docs explicitly state only Recipient counterparties can be deleted through the API; Sender cleanup must go through your account manager.

Get addresses for a specific counterparty using Counterparty/getCounterpartyAddresses (doc 1.6). Requires API key plus CounterpartyProperty/Ref and, per docs, should be refreshed daily because every page is capped at 500 entries.

Get contact persons for a counterparty through Counterparty/getCounterpartyContactPersons (doc 1.6). API key is mandatory and the list should be cached daily; use paging to stay under the 500-record response cap.

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 (warehouse-door etc.) through Common/getServiceType (doc 1.9). Docs say to refresh monthly and point out the four core technologies: WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors.

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 (Internet document) via InternetDocument/save (doc 1.2). This is the basic waybill creation method. For additional services use waybill_create_with_options. For postomat delivery use waybill_create_for_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.

Create a waybill for postomat delivery via InternetDocument/save (doc 1.2). Postomats have size/weight restrictions (max 30kg, max dimensions). Requires proper warehouse selection (postomat type) and seat options configuration.

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.