Nova Poshta (old) data API

ТОВ «Нова пошта» · Transport

Nova poshta (old) is the long-running Android client of ТОВ «Нова пошта», Ukraine's largest private parcel carrier, published under the Play listing that predates the newer NovaPost brand. After OAuth sign-in (or a loyalty-card / phone login), a sender creates an internet waybill, prices a warehouse-to-warehouse or doors-to-doors shipment, tracks a 14-digit ТТН, redirects or returns a parcel, books a courier pickup, and looks up branch hours on the map; the same session holds a loyalty card with a barcode, money-transfer documents, postomat (parcel locker) PIN codes, RedBox orders, and NovaPay card checkout. Households, marketplace sellers and small shops in Ukraine use it next to Ukrposhta, Meest and the EU-facing NovaPost apps, and the listing still carries the "old" suffix because Nova Poshta has been migrating users onto novapost.com while this client continues to serve the domestic Ukrainian network.

Internet waybills are the unit of record: each ТТН carries IntDocNumber, StatusCode, sender and recipient cities, DocumentCost and flags such as possibilityCreateReturn. Movement legs split into now / passed / future, locker drop-offs expose postomatCode, and cash-on-delivery sits on moneyTransferAmount plus moneyTransferCommission.

The branch catalog is a geo index of WarehouseIndex, Latitude, Longitude and weight caps, while the loyalty card returns loyaltyCardNumber, discount and turnover Scores. Marketplace ERPs reconcile dispatch, checkout widgets pick a locker that fits the parcel, and bookkeeping bots match COD payouts — openData Studio turns those fields into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Track waybill status

POST /v1/novaposhtaa/track opendata

Looks up live ТТН status, counterparties, warehouse, COD/card flags and postomat PIN that power the track-delivery screens.

Auth: Loyalty card key in the JSON body when signed in; public tracking can omit it. Optional Authorization: Bearer <session-token>.

Number
StatusCode
Status
CitySender
CityRecipient
WarehouseRecipient
RecipientDateTime
ScheduledDeliveryDate
DocumentCost
DocumentWeight
CargoDescriptionString
PayerType
PaymentMethod
possibilityCreateReturn
possibilityForRedirecting
postomatCode
CardMaskedNumber

POST /v1/novaposhtaa/track HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "documents": [
    {"documentNumber": "20450123456789", "phone": "380671234567"}
  ],
  "language": "UA"
}

{
  "success": true,
  "data": [{
    "Number": "20450123456789",
    "StatusCode": "7",
    "Status": "Arrived at the warehouse",
    "CitySender": "Київ",
    "CityRecipient": "Львів",
    "WarehouseRecipient": "Відділення №12",
    "RecipientDateTime": "12.10.2026 18:40:00",
    "ScheduledDeliveryDate": "12.10.2026",
    "DocumentCost": "85.00",
    "DocumentWeight": "2.4",
    "CargoDescriptionString": "Одяг",
    "PayerType": "Sender",
    "PaymentMethod": "Cash",
    "possibilityCreateReturn": true,
    "possibilityForRedirecting": true,
    "postomatCode": "4821",
    "CardMaskedNumber": "5168****1234"
  }]
}

List internet waybills

GET /v1/novaposhtaa/waybills opendata

Pages the signed-in user's created waybills (including not-yet-handed-over cargo) for the consignments list.

Auth: Loyalty card key plus optional Bearer <session-token>.

Ref
IntDocNumber
Cost
CostOnSite
CitySender
CityRecipient
RecipientFullName
RecipientsPhone
PayerType
PaymentMethod
ServiceType
SeatsAmount
Weight
State
DateTime

GET /v1/novaposhtaa/waybills?full=true&from=2026-09-01&to=2026-10-09&notSent=1 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "a1b2c3d4-1111-2222-3333-444455556666",
    "IntDocNumber": "20450123456789",
    "Cost": "1200",
    "CostOnSite": 85,
    "CitySender": "Київ",
    "CityRecipient": "Одеса",
    "RecipientFullName": "Іван Петренко",
    "RecipientsPhone": "380931112233",
    "PayerType": "Sender",
    "PaymentMethod": "Cash",
    "ServiceType": "WarehouseWarehouse",
    "SeatsAmount": "1",
    "Weight": "1.5",
    "State": "1",
    "DateTime": "08.10.2026 14:22:00"
  }]
}

Create internet waybill

POST /v1/novaposhtaa/waybills opendata

Creates (or updates) an internet waybill from the consignment flow and returns the ТТН number plus on-site tariff.

Auth: Loyalty card key in the JSON body. Optional Bearer <session-token>.

PayerType
PaymentMethod
CargoType
Weight
ServiceType
SeatsAmount
Description
Cost
CitySender
Sender
SendersPhone
CityRecipient
Recipient
RecipientsPhone
OptionsSeat
Ref
IntDocNumber
CostOnSite
EstimatedDeliveryDate

POST /v1/novaposhtaa/waybills HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "payerType": "Sender",
  "paymentMethod": "Cash",
  "cargoType": "Cargo",
  "weight": "2.4",
  "serviceType": "WarehouseWarehouse",
  "seatsAmount": "1",
  "description": "Одяг",
  "cost": "1200",
  "citySender": "<city_ref>",
  "sender": "<counterparty_ref>",
  "senderAddress": "<warehouse_ref>",
  "sendersPhone": "380671234567",
  "cityRecipient": "<city_ref>",
  "recipient": "<recipient_ref>",
  "recipientAddress": "<recipient_warehouse_ref>",
  "recipientsPhone": "380931112233",
  "optionsSeat": [{
    "volumetricWidth": "20",
    "volumetricLength": "30",
    "volumetricHeight": "15",
    "weight": "2.4"
  }]
}

{
  "success": true,
  "data": {
    "Ref": "a1b2c3d4-1111-2222-3333-444455556666",
    "IntDocNumber": "20450123456789",
    "CostOnSite": 85,
    "EstimatedDeliveryDate": "12.10.2026",
    "TypeDocument": "InternetDocument"
  }
}

Quote waybill price

POST /v1/novaposhtaa/quote opendata

Returns the on-site tariff (and COD/redelivery add-on) for the CalculateCargo / consignment price step.

Auth: Loyalty card key in the JSON body. Optional Bearer <session-token>.

CitySender
CityRecipient
Weight
ServiceType
Cost
CargoType
SeatsAmount
RedeliveryCalculate
CostRedelivery
AssessedCost
CostPack

POST /v1/novaposhtaa/quote HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "citySender": "<city_ref>",
  "cityRecipient": "<city_ref>",
  "weight": "2.4",
  "serviceType": "WarehouseWarehouse",
  "cost": "1200",
  "cargoType": "Cargo",
  "seatsAmount": "1",
  "redeliveryCalculate": {
    "cargoType": "Money",
    "amount": "1200"
  }
}

{
  "success": true,
  "data": {
    "Cost": 85,
    "CostRedelivery": 20,
    "AssessedCost": 1200,
    "CostPack": 0
  }
}

Waybill movement timeline

GET /v1/novaposhtaa/waybills/{number}/legs opendata

Returns the past / current / upcoming movement legs that fill the EW movement map and history screen.

Auth: Loyalty card key plus optional Bearer <session-token>.

Number
now
passed
future
Status
StatusCode
Date
City
Warehouse

GET /v1/novaposhtaa/waybills/20450123456789/legs?format=timeline HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": {
    "Number": "20450123456789",
    "now": [{
      "Status": "Arrived at the warehouse",
      "StatusCode": "7",
      "Date": "12.10.2026 18:40:00",
      "City": "Львів",
      "Warehouse": "Відділення №12"
    }],
    "passed": [{
      "Status": "Departed from sender warehouse",
      "StatusCode": "5",
      "Date": "10.10.2026 09:15:00",
      "City": "Київ"
    }],
    "future": [{
      "Status": "Received by the recipient"
    }]
  }
}

Open shipments by phone

GET /v1/novaposhtaa/inbox opendata

Lists still-open waybills tied to the loyalty-card phone for the inbox of inbound / outbound parcels.

Auth: Loyalty card key plus optional Bearer <session-token>.

Phone
Page
Limit
IntDocNumber
CityRecipient
RecipientFullName
StatusCode
DocumentCost
DateTime

GET /v1/novaposhtaa/inbox?phone=380671234567&page=1&limit=100 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "IntDocNumber": "20450123456789",
    "CityRecipient": "Львів",
    "RecipientFullName": "Іван Петренко",
    "StatusCode": "7",
    "DocumentCost": "85.00",
    "DateTime": "08.10.2026 14:22:00"
  }]
}

Loyalty card profile

GET /v1/novaposhtaa/card osint

Loads the signed-in loyalty-card holder (barcode, discount, counterparty, phones) that fills Cabinet and ShowDiscountCard.

Auth: Loyalty card key plus optional Bearer <session-token>.

loyaltyCardNumber
loyaltyCardBarcode
loyaltyCardType
discount
phone
email
fullName
counterpartyRef
cityRef
cid
additionalPhones

GET /v1/novaposhtaa/card HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": {
    "loyaltyCardNumber": "9000123456789",
    "loyaltyCardBarcode": "9000123456789",
    "loyaltyCardType": "Personal",
    "discount": 2.0,
    "phone": "380671234567",
    "email": "[email protected]",
    "fullName": "Іван Петренко",
    "counterpartyRef": "c0ffee00-1111-2222-3333-444455556666",
    "cityRef": "<city_ref>",
    "cid": "cid_88421",
    "additionalPhones": ["380931112233"]
  }
}

Loyalty card turnover

GET /v1/novaposhtaa/card/ledger openfinance

Returns loyalty-card shipment turnover (sum, scores, counterparties) for the TransactionHistory screen.

Auth: Loyalty card key plus optional Bearer <session-token>.

DateFrom
DateTo
Document
Date
Sum
Scores
Type
CitySender
CityRecipient
Sender
Recipient
CargoType
PaymentMethod

GET /v1/novaposhtaa/card/ledger?from=2026-01-01&to=2026-10-09 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Document": "20450123456789",
    "Date": "08.10.2026",
    "Sum": "85.00",
    "Scores": "2",
    "Type": "Shipment",
    "CitySender": "Київ",
    "CityRecipient": "Львів",
    "Sender": "Іван Петренко",
    "Recipient": "Олена Коваль",
    "CargoType": "Cargo",
    "PaymentMethod": "Cash"
  }]
}

Money transfer documents

GET /v1/novaposhtaa/transfers openfinance

Pages cash-on-delivery / money-transfer documents (amount, commission, cash2card) for MoneyTransferDocumentsActivity.

Auth: Loyalty card key plus optional Bearer <session-token>.

Page
Limit
DateFrom
DateTo
Ref
Number
moneyTransferNumber
moneyTransferAmount
moneyTransferCommission
moneyTransferPayerCommission
moneyTransferPayerType
moneyTransferPaymentMethod
moneyTransferStatus
moneyTransferStatusDateTime
moneyTransferCash2Card

GET /v1/novaposhtaa/transfers?page=1&limit=50&from=2025-10-09&to=2026-10-09 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "d0c0ffee-aaaa-bbbb-cccc-ddddeeeeffff",
    "Number": "20450999887766",
    "moneyTransferNumber": "MT-88421",
    "moneyTransferAmount": "3500.00",
    "moneyTransferCommission": "35.00",
    "moneyTransferPayerCommission": "Sender",
    "moneyTransferPayerType": "Sender",
    "moneyTransferPaymentMethod": "Cash",
    "moneyTransferStatus": "Issued",
    "moneyTransferStatusDateTime": "08.10.2026 16:05:00",
    "moneyTransferCash2Card": false,
    "moneyTransferCreationDate": "07.10.2026 11:20:00"
  }]
}

Init shipment payment

POST /v1/novaposhtaa/checkout openfinance

Starts a NovaPay / card checkout for a waybill (delivery fee or after-payment) from ChoosePaymentActivity.

Auth: Loyalty card key in the JSON body. Optional Bearer <session-token>.

Document
Phone
Services
AfterPayments
TransactionId
PaymentSystem
Amount
SuccessUrl
ErrorUrl

POST /v1/novaposhtaa/checkout HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "document": "20450123456789",
  "phone": "380671234567",
  "services": [{"serviceCode": "Delivery", "amount": "85.00"}],
  "afterPayments": []
}

{
  "success": true,
  "data": {
    "TransactionId": "npay_9f21a",
    "PaymentSystem": "NovaPay",
    "Amount": "85.00",
    "Document": "20450123456789",
    "SuccessUrl": "https://pay.example.com/result",
    "ErrorUrl": "https://pay.example.com/result"
  }
}

Warehouse catalog

GET /v1/novaposhtaa/branches opendata

Returns branch / postomat rows (index, geo, weight limits, POS and PostFinance flags) for FindOffice and the local warehouse DB.

Auth: Shared or user card key. Catalog download can also run on the unsigned background client.

CityRef
Language
Ref
SiteKey
Description
DescriptionRu
ShortAddress
CityDescription
Number
WarehouseIndex
TypeOfWarehouse
CategoryOfWarehouse
Latitude
Longitude
TotalMaxWeightAllowed
PlaceMaxWeightAllowed
PosTerminal
PostFinance
BicycleParking
InternationalShipping

GET /v1/novaposhtaa/branches?city=<city_ref>&language=UA HTTP/1.1
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "1ec09d2b-e1c2-11e3-8c4a-0050568002cf",
    "SiteKey": 10122,
    "Description": "Відділення №12: вул. Городоцька, 174",
    "DescriptionRu": "Отделение №12: ул. Городоцкая, 174",
    "ShortAddress": "Львів, Городоцька, 174",
    "CityRef": "<city_ref>",
    "CityDescription": "Львів",
    "Number": "12",
    "WarehouseIndex": "79000",
    "TypeOfWarehouse": "9a68df70-0267-42ba-8dd1-badd982d3dcb",
    "CategoryOfWarehouse": "Branch",
    "Latitude": "49.8397",
    "Longitude": "24.0297",
    "TotalMaxWeightAllowed": 1000,
    "PlaceMaxWeightAllowed": 30,
    "PosTerminal": "1",
    "PostFinance": "1",
    "BicycleParking": "1",
    "InternationalShipping": "1"
  }]
}

Search settlements

GET /v1/novaposhtaa/cities opendata

Autocomplete for Ukrainian settlements used by SearchCityFromNpServer and the consignment city pickers.

Auth: May run without a card key for the city picker.

CityName
Limit
TotalCount
Addresses
Present
Warehouses
MainDescription
Area
Region
SettlementRef
DeliveryCity

GET /v1/novaposhtaa/cities?q=%D0%9B%D1%8C%D0%B2%D1%96%D0%B2&limit=20 HTTP/1.1

{
  "success": true,
  "data": {
    "TotalCount": 3,
    "Addresses": [{
      "Present": "м. Львів, Львівська обл.",
      "Warehouses": 142,
      "MainDescription": "Львів",
      "Area": "Львівська",
      "Region": "Львівський",
      "SettlementRef": "<city_ref>",
      "DeliveryCity": "<city_ref>"
    }]
  }
}

Data categories

waybills
tracking
warehouses
loyalty
money-transfers
payments

Where teams use this data

Marketplace dispatch reconciliation
A seller's ERP pulls open waybills by phone and the dated document list, then matches IntDocNumber, DocumentCost and StatusCode against orders so unpaid or not-yet-handed-over parcels are flagged before the cutoff.
Branch finder for checkout
A checkout widget searches settlements, then lists warehouses with WarehouseIndex, Latitude/Longitude and PlaceMaxWeightAllowed so a buyer picks a locker or branch that can actually take the parcel.
COD and loyalty ledger
A bookkeeping bot pages money-transfer documents (moneyTransferAmount, moneyTransferCommission, moneyTransferCash2Card) and loyalty turnover (Sum, Scores) to reconcile cash-on-delivery payouts against the card holder's discount.
Recipient ETA and locker PIN
A consignee bot tracks a ТТН for ScheduledDeliveryDate, RecipientDateTime and postomatCode, then notifies the buyer when the parcel is at the locker and a return or redirect is still allowed.

Frequently asked questions

How does Nova Poshta identify a parcel in its data API?

Each internet waybill is an IntDocNumber (the 14-digit ТТН) plus a Ref. Tracking looks up DocumentNumber (and optionally the recipient Phone); creating a waybill returns IntDocNumber, CostOnSite and EstimatedDeliveryDate.

What warehouse fields can a checkout integration read?

The branch catalog returns Ref, WarehouseIndex, Description, CityDescription, Latitude, Longitude, TypeOfWarehouse, PlaceMaxWeightAllowed, PosTerminal and PostFinance so a buyer can pick a branch or postomat that accepts the weight and has a POS.

Does the app expose loyalty and money-transfer data, not just tracking?

Yes. The loyalty card returns loyaltyCardNumber, discount, phone and counterpartyRef; the card ledger pages Sum and Scores. Money-transfer documents return moneyTransferAmount, moneyTransferCommission and moneyTransferCash2Card.

How does a signed-in session authenticate?

Most calls send the user's card key in the JSON envelope with a MobileApp system hint. After OAuth login a Bearer session token is attached as well. City search can run without a card key.

Apps similar to Nova poshta (old)

Ukrposhta — Ukrposhta is Ukraine's state postal operator, offering parcel post, courier delivery and online tracking through its national post-office network; Wikipedia names it Nova Poshta's main competitor.
Nova Post — Nova Post is the current Android client (eu.novapost) listed on novaposhta.ua for creating a shipment, reviewing details and managing parcels after the international Nova Post brand.
Meest — Meest is a Ukrainian postal-logistics operator with own and partner branches for domestic parcels and international shipping to 70+ countries, plus a mobile app for tracking.
Justin — Justin is a Ukrainian last-mile service that delivers e-commerce parcels to pickup points at Silpo supermarket checkouts instead of standalone branches.
Delivery Auto — Delivery Auto is a Ukrainian cargo carrier that ships from boxes to pallets nationwide, with online tracking, courier pickup and a mobile app for receipts and shipments.
UPS — UPS is United Parcel Service's Android client for tracking packages, scheduling pickups and locating drop-off points, covering the same sender tasks on international routes.
Packeta — Packeta (Zásilkovna) is a Central European pickup-point and parcel-locker network for e-commerce, and its site lists Ukraine among delivery destinations.

More Transport apps

Topics

Nova Poshta API
Nova poshta old
TTN tracking
IntDocNumber
Ukrainian warehouses
loyalty card turnover
money transfer documents
postomat PIN

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Nova Poshta (old) data API

Screenshots

API surface

Track waybill status

List internet waybills

Create internet waybill

Quote waybill price

Waybill movement timeline

Open shipments by phone

Loyalty card profile

Loyalty card turnover

Money transfer documents

Init shipment payment

Warehouse catalog

Search settlements

Data categories

Where teams use this data

Marketplace dispatch reconciliation

Branch finder for checkout

COD and loyalty ledger

Recipient ETA and locker PIN

Frequently asked questions

Apps similar to Nova poshta (old)

More Transport apps

99 Motorista e Entregador

Amazon Flex

Australia Post

Borzo: Courier Delivery App

Topics

Need this app's data API integrated?

Nova Poshta (old) data API

Screenshots

API surface

Track waybill status

List internet waybills

Create internet waybill

Quote waybill price

Waybill movement timeline

Open shipments by phone

Loyalty card profile

Loyalty card turnover

Money transfer documents

Init shipment payment

Warehouse catalog

Search settlements

Data categories

Where teams use this data

Marketplace dispatch reconciliation

Branch finder for checkout

COD and loyalty ledger

Recipient ETA and locker PIN

Frequently asked questions

Related apps

Apps similar to Nova poshta (old)

More Transport apps

99 Motorista e Entregador

Amazon Flex

Australia Post

Borzo: Courier Delivery App

Topics

Need this app's data API integrated?