Nova Post waybill and locker data API

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

Nova Post is the official Android app from ТОВ «Нова пошта» (Nova Poshta) for households and small senders using its Ukrainian courier service and international Nova Post network. Users create waybills, follow inbound and outbound parcels, choose a branch or postomat locker, book courier collection and pay postage with NovaPay or loyalty points. The home feed brings together parcel updates, locker access cards, nearby service points, promotional offers and customs declaration bills. Ukrainian, English and other European language options support senders across the network. It is the current first-party client alongside the legacy Nova poshta (old) app, rather than a multi-carrier tracking service.

Waybill timelines connect onlineTrackingStatusCode with dated event_name entries, settlement_name and scheduledDeliveryDate. Shipment records add sender and recipient details, parcel weights, declared value and available actions. Postage charges appear as totalCost and currencyCode, while paymentStatus and moneyTransferStatus distinguish checkout progress from cash-on-delivery transfer state.

Service-point records pair lat and lon with divisionCategory, opening status and alarm flags; locker availability adds isAvailablePostomat and collection cards carry recipientCode, uploadCode and an expiry time. Booked collections link pickedTimeFrom and pickedTimeTo to courier details, vehicle position and the associated waybills. Saved addresses, eligible promotional offers and versioned parcel updates complement those delivery records.

Marketplace order systems can match delivery events to dispatch milestones, warehouse teams can combine service-point availability with collection windows, and finance teams can reconcile postage and cash-on-delivery state. openData Studio turns these records into callable open data for those integrations. The API paths and example values below are illustrative, and account-linked contact details, locker codes and courier information require authorized access.

Screenshots

API surface

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

Track shipment by id

GET /v1/parcels/{id}/timeline opendata

Returns the live tracking timeline and status code for a waybill shown on the tracking screen.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

id
number
onlineTracking
tracking_status_code
short_description
long_description
label
tracking
event
event_name
event_status
settlement_name
country_code
onlineTrackingStatusCode
onlineTrackingShortDescription
scheduledDeliveryDate
status

GET /v1/parcels/{id}/timeline HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "parcel-demo-001",
  "number": "DEMO-WAYBILL-001",
  "onlineTracking": {
    "tracking_status_code": 1,
    "short_description": "Awaiting handover",
    "long_description": "The sender has created the waybill and has not handed over the parcel.",
    "info": "",
    "label": "orange"
  },
  "tracking": [
    {
      "number": "DEMO-WAYBILL-001",
      "date": "2026-10-27T09:00:00Z",
      "division": "point-demo-001",
      "event": "CreateID",
      "event_status": "now",
      "country_code": "UA",
      "code": "1",
      "settlement_name": "Kyiv",
      "event_name": "Waybill created; parcel not yet handed over"
    }
  ],
  "onlineTrackingStatusCode": 1,
  "onlineTrackingShortDescription": "Awaiting handover",
  "scheduledDeliveryDate": "2026-10-28T16:00:00Z",
  "status": "ReadyToShip"
}

Get shipment detail

GET /v1/parcels/{id}/details opendata

Loads the full waybill used by shipment detail: parties, dimensions, totals and action flags.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

id
number
status
paymentStatus
currencyCode
parcelsAmount
payerType
sender
recipient
phone
countryCode
settlement_id
settlement_name
divisionId
divisionCategory
serviceType
parcels
cargo_category_group
insurance_cost
actual_weight
totalWeight
totalInsuranceCost
totalCost
moneyTransferStatus
parcel_actions
canPay

GET /v1/parcels/{id}/details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "parcel-demo-001",
  "number": "DEMO-WAYBILL-001",
  "status": "ReadyToShip",
  "paymentStatus": "NeedPay",
  "currencyCode": "UAH",
  "parcelsAmount": 1,
  "payerType": "Sender",
  "sender": {
    "phone": "<sender-phone>",
    "name": "Example Sender",
    "countryCode": "UA",
    "settlement_id": "city-demo-001",
    "settlement_name": "Kyiv",
    "divisionId": "point-demo-001",
    "division_name": "Example branch 1",
    "divisionCategory": "PostBranch",
    "serviceType": "Division"
  },
  "recipient": {
    "phone": "<recipient-phone>",
    "name": "Example Recipient",
    "countryCode": "UA",
    "settlement_id": "city-demo-002",
    "settlement_name": "Lviv",
    "divisionId": "point-demo-002",
    "divisionCategory": "PostBranch",
    "serviceType": "Division"
  },
  "parcels": [
    {
      "number": "DEMO-WAYBILL-001",
      "cargo_category_group": "document",
      "insurance_cost": 300,
      "length": 30,
      "width": 20,
      "height": 2,
      "actual_weight": 0.8
    }
  ],
  "totalWeight": 0.8,
  "totalInsuranceCost": 300,
  "totalCost": 80,
  "moneyTransferStatus": null,
  "parcel_actions": {
    "canPay": true,
    "canPrint": true,
    "canEdit": true
  }
}

Calculate shipment tariff

POST /v1/rates/estimate opendata

Quotes postage and extra services before the create-parcel wizard commits a waybill.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

senderCountryCode
recipientCountryCode
senderServiceType
recipientServiceType
actual_weight
insurance_cost
payerType
currencyCode
totalCost
totalInsuranceCost
totalWeight
services
service_type
service_name
cost
price
discount
payment_status

POST /v1/rates/estimate HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "senderCountryCode": "UA",
  "recipientCountryCode": "UA",
  "senderServiceType": "Division",
  "recipientServiceType": "Postomat",
  "actual_weight": 1.2,
  "length": 25,
  "width": 20,
  "height": 12,
  "insurance_cost": 400,
  "payerType": "Sender",
  "currencyCode": "UAH"
}

{
  "currencyCode": "UAH",
  "totalCost": 85.0,
  "totalInsuranceCost": 400.0,
  "totalWeight": 1.2,
  "services": [
    {
      "service_type": "MainService",
      "service_name": "Example domestic parcel delivery",
      "cost": 85.0,
      "price": 85.0,
      "discount": 0,
      "payer_type": "Sender",
      "payment_status": "NeedPay",
      "currency_code": "UAH"
    }
  ]
}

Postomat locker open codes

GET /v1/locker-access/{number}/codes opendata

Issues the recipient PIN, drop-off code and Bluetooth MAC used to open a postomat cell.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

shipmentNumber
recipientCode
uploadCode
bluetoothMacAddress
expirationDate
isQrGenerated
postomatProducer

GET /v1/locker-access/{number}/codes HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "shipmentNumber": "DEMO-WAYBILL-001",
  "recipientCode": "<pickup-pin>",
  "uploadCode": "<dropoff-code>",
  "bluetoothMacAddress": "<locker-bluetooth-address>",
  "expirationDate": "2026-10-29T18:00:00Z",
  "isQrGenerated": true,
  "postomatProducer": "Example locker provider"
}

Available parcel lockers

GET /v1/locker-locations/availability opendata

Lists lockers that still have a free cell for the parcel being sent or redirected.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

id
titleName
titleNumber
divisionCategory
address
lat
lon
settlement
countryCode
isAvailablePostomat
postomatProducer
maxInsuranceCost
scheduleList

GET /v1/locker-locations/availability HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "id": "locker-demo-001",
      "titleName": "Example locker 7",
      "titleNumber": "7",
      "divisionCategory": "Postomat",
      "address": "Example Street 10, Kyiv",
      "lat": 50.45,
      "lon": 30.52,
      "settlement": "Kyiv",
      "countryCode": "UA",
      "isAvailablePostomat": true,
      "postomatProducer": "Example locker provider",
      "maxInsuranceCost": 12000.0,
      "scheduleList": [
        "08:00-20:00"
      ]
    }
  ]
}

Courier vehicle coordinates
GET /v1/delivery-runs/{shipmentNumber}/position opendata
Streams the courier vehicle position used by the on-map tracking card.
Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email
- shipmentNumber
- latitude
- longitude
- coordinatesStatus
- canGetCourierRoute
```
GET /v1/delivery-runs/{shipmentNumber}/position HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
```
```
{
  "shipmentNumber": "DEMO-WAYBILL-001",
  "latitude": 50.451,
  "longitude": 30.521,
  "coordinatesStatus": "live",
  "canGetCourierRoute": true
}
```

Division alarm status

GET /v1/service-points/availability opendata

Flags branches that are closed or under an alarm so the map and pickup wizard can skip them.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

divisions
id
titleName
alarm
isDivisionOpen
countryCode
settlement
lat
lon

GET /v1/service-points/availability HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "divisions": [
    {
      "id": "point-demo-001",
      "titleName": "Example branch 1",
      "alarm": false,
      "isDivisionOpen": true,
      "countryCode": "UA",
      "settlement": "Kyiv",
      "lat": 50.45,
      "lon": 30.52
    }
  ]
}

Courier pickup order

GET /v1/collections/{id}/details opendata

Returns a booked courier pickup with time window, assigned courier and linked waybills.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

id
number
status
statusDateTime
countryCode
fullName
phone
settlementName
settlementId
pickedTimeFrom
pickedTimeTo
isExpressDelivery
cargoType
weight
volumetricWeight
parcelsAmount
payerType
paymentMethod
courier
courierId
courierName
courierPhone
vehicleNumber
shipments
shipmentId
shipmentNumber

GET /v1/collections/{id}/details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "collection-demo-001",
  "number": "DEMO-COLLECTION-001",
  "status": "Assigned",
  "statusDateTime": "2026-10-27T08:00:00Z",
  "countryCode": "UA",
  "fullName": "Example Sender",
  "phone": "<sender-phone>",
  "settlementName": "Kyiv",
  "settlementId": 100001,
  "pickedTimeFrom": "2026-10-28T09:00:00Z",
  "pickedTimeTo": "2026-10-28T12:00:00Z",
  "isExpressDelivery": false,
  "cargoType": "Parcel",
  "weight": 1.2,
  "volumetricWeight": 1.5,
  "parcelsAmount": 1,
  "payerType": "Sender",
  "paymentMethod": "Cash",
  "courier": {
    "courierId": "courier-demo-001",
    "courierName": "Example Courier",
    "courierPhone": "<courier-phone>",
    "vehicleNumber": "<vehicle-registration>"
  },
  "shipments": [
    {
      "shipmentId": "parcel-demo-001",
      "shipmentNumber": "DEMO-WAYBILL-001"
    }
  ]
}

Courier time intervals

GET /v1/collection-slots opendata

Lists bookable courier pickup windows for the create-parcel and reschedule flows.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

date
number
start
end
boundaryTime
deliveryPartner
minutesToPickUp

GET /v1/collection-slots HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "date": "2026-10-28",
      "number": "1",
      "start": "09:00",
      "end": "12:00",
      "boundaryTime": "08:15",
      "deliveryPartner": "NovaPoshta",
      "minutesToPickUp": 45
    }
  ]
}

Client profile

GET /v1/account/contact-details osint

Reads the signed-in sender profile used to prefill create-parcel and favorite points.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

phone
name
email
countryCode
eoriCode
favoriteAddresses
favoriteAddressId
settlementName
address
divisionId

GET /v1/account/contact-details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "phone": "<sender-phone>",
  "name": "Example Sender",
  "email": "<sender-email>",
  "countryCode": "UA",
  "eoriCode": null,
  "favoriteAddresses": [
    {
      "favoriteAddressId": "address-demo-001",
      "settlementName": "Kyiv",
      "address": "Example Street 10, Kyiv",
      "divisionId": null
    }
  ]
}

Favorite delivery addresses

GET /v1/address-book/entries opendata

Lists saved sender/recipient addresses offered as one-tap destinations.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

favoriteAddresses
favoriteAddressId
city
street
building
postCode
countryCode
latitude
longitude
addressId

GET /v1/address-book/entries HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "favoriteAddresses": [
    {
      "favoriteAddressId": "address-demo-001",
      "city": "Kyiv",
      "street": "Example Street",
      "building": "10",
      "postCode": "01001",
      "countryCode": "UA",
      "latitude": 50.45,
      "longitude": 30.52,
      "addressId": "address-demo-001"
    }
  ]
}

Shipment payment status

GET /v1/postage/{number}/payment-state openbanking

Reads NovaPay checkout state for a waybill, including COD money-transfer status.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

number
paymentStatus
currencyCode
totalCost
payerType
isPaymentProcessing
moneyTransferStatus
payments
source
amount
status

GET /v1/postage/{number}/payment-state HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "number": "DEMO-WAYBILL-001",
  "paymentStatus": "NeedPay",
  "currencyCode": "UAH",
  "totalCost": 80.0,
  "payerType": "Sender",
  "isPaymentProcessing": false,
  "moneyTransferStatus": null,
  "payments": [
    {
      "source": "NovaPay",
      "amount": 80.0,
      "status": "NeedPay"
    }
  ]
}

Pay with loyalty points

POST /v1/postage/{number}/redeem-points openfinance

Settles postage against the sender's Nova Poshta loyalty card instead of NovaPay.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

loyaltyCardNumber
number
paymentStatus
currencyCode
totalCost

POST /v1/postage/{number}/redeem-points HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "loyaltyCardNumber": "DEMO-LOYALTY-001",
  "number": "DEMO-WAYBILL-001"
}

{
  "number": "DEMO-WAYBILL-001",
  "paymentStatus": "Paid",
  "loyaltyCardNumber": "DEMO-LOYALTY-001",
  "currencyCode": "UAH",
  "totalCost": 0.0
}

List shipment promo codes

GET /v1/delivery-offers opendata

Lists redeemable promo codes shown on the apply-promocode shipment menu.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

promoCode
dateOfEnding
note
auto
deliveryChanel
details
Valid

GET /v1/delivery-offers HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "promoCode": "DEMO-OFFER-15",
      "dateOfEnding": "2026-11-30",
      "note": "Illustrative 15% discount on eligible parcels",
      "auto": "false",
      "deliveryChanel": "mobile",
      "details": [
        "domestic",
        "eligible parcels"
      ],
      "Valid": true
    }
  ]
}

Sync shipment versions

GET /v1/parcel-updates opendata

Pages incremental waybill versions so background synchronization can refresh locally stored shipment records.

Auth: Bearer access token following OpenID Connect sign-in; scopes openid offline name phone email

items
id
number
version
updatedAt
deletedAt
status
current_page
per_page
last_page
total

GET /v1/parcel-updates HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "id": "parcel-demo-001",
      "number": "DEMO-WAYBILL-001",
      "version": 12,
      "updatedAt": "2026-10-27T09:05:00Z",
      "deletedAt": null,
      "status": "ReadyToShip"
    }
  ],
  "current_page": 1,
  "per_page": 15,
  "last_page": 1,
  "total": 1
}

Where teams use this data

Marketplace waybill tracking
Checkout backends that already print a Nova Poshta barcode can poll onlineTrackingStatusCode, event_name and scheduledDeliveryDate to flip an order from ReadyToShip to delivered without scraping the public tracker.
Locker and branch overlay
Last-mile maps merge division lat/lon, divisionCategory and isAvailablePostomat with recipientCode/uploadCode so a shopper sees which postomat still has a free cell and can open it on arrival.
NovaPay and COD reconciliation
Finance jobs match paymentStatus, totalCost, currencyCode and moneyTransferStatus against the merchant ledger so unpaid waybills and cash-on-delivery payouts stay in sync.
Courier pickup windows
Warehouse dispatch reads pickedTimeFrom/pickedTimeTo plus live latitude/longitude so a pickup slot and the approaching vehicle land on the same operations board.

Frequently asked questions

Which Nova Post tracking and NovaPay payment fields support order reconciliation?

Waybill tracking includes onlineTrackingStatusCode and a timeline with event, event_name, settlement_name and country_code. Shipment details add scheduledDeliveryDate, parcel status, sender and recipient information, and totalCost. Payment records provide paymentStatus, totalCost, currencyCode, payerType, isPaymentProcessing and moneyTransferStatus, while loyalty payments associate loyaltyCardNumber with the waybill number and resulting paymentStatus. These fields let order and finance systems match delivery milestones with postage and cash-on-delivery state. The paths, amounts and identifiers shown are illustrative, not live tariffs or payment results.

Which fields describe postomat locker access and availability?

Locker access records include recipientCode for collection, uploadCode for drop-off, bluetoothMacAddress and expirationDate. Locker availability records add lat, lon, isAvailablePostomat, postomatProducer and scheduleList. Access codes belong to the authorized shipment workflow, not a public directory of working PINs.

How is access to account-linked Nova Post data authenticated?

The account flow uses OpenID Connect sign-in and Bearer access tokens. The examples use a token placeholder and generalized paths; they do not supply a working sign-in configuration. Contact information, saved addresses and shipment-specific locker access require appropriate authorization.

Can branch locations and courier pickup windows be combined?

Service-point records provide id, lat, lon, alarm and isDivisionOpen. Booked collections include pickedTimeFrom, pickedTimeTo, courierName, vehicleNumber and linked shipmentNumber values. Available time windows add start, end, boundaryTime and minutesToPickUp for scheduling.

Apps similar to Nova Post

Nova poshta (old) — Nova poshta (old) is the long-running Android client from the same publisher, ТОВ «Нова пошта», for creating, tracking, paying and redirecting Nova Poshta waybills and calling a courier.
Ukrposhta — Ukrposhta is Ukraine's 100% state-owned national postal service, providing universal postal, logistics, financial and courier services including mail, express mail and parcel post.
Meest Poshta — Meest POSHTA is the official Android app for Meest parcel delivery in Ukraine and abroad, used to create shipments online, track them around the clock, pay for delivery and find branches and parcel lockers on a map.
Delivery Auto — Delivery Auto is a Ukrainian cargo carrier that ships from boxes to pallets nationwide, and its Android app tracks consignments by receipt number, lists representative offices and estimates price and transit time.
Justin — Justin is a Ukrainian parcel service whose pickup points sit inside Silpo supermarkets, so shoppers can send and collect orders where they already buy groceries.
UPS — UPS is the official Android app of United Parcel Service for creating shipping labels, tracking inbound and outbound packages, quoting rates and locating drop-off points.
DHL Express Mobile — DHL Express Mobile is the official Android app of DHL Express for tracking shipments, managing deliveries, locating Service Points and checking shipping rates.
Packeta — Packeta (Zásilkovna) is a Central European pickup-point and Z-BOX locker network whose Czech site lists Ukraine among destinations for pick-up-point and home delivery.

More Transport apps

Topics

nova post api
nova poshta waybill tracking
postomat locker availability
ukraine courier data
novapay payment status
courier pickup windows
nova post branch locations
waybill onlineTrackingStatusCode

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 Post waybill and locker data API

Screenshots

API surface

Track shipment by id

Get shipment detail

Calculate shipment tariff

Postomat locker open codes

Available parcel lockers

Courier vehicle coordinates

Division alarm status

Courier pickup order

Courier time intervals

Client profile

Favorite delivery addresses

Shipment payment status

Pay with loyalty points

List shipment promo codes

Sync shipment versions

Data categories

Where teams use this data

Marketplace waybill tracking

Locker and branch overlay

NovaPay and COD reconciliation

Courier pickup windows

Frequently asked questions

Apps similar to Nova Post

More Transport apps

Careem Captain

Delhivery: Courier App

DiDi Driver: Drive & Earn Cash

Dostavista — работа курьером

Topics

Need this app's data API integrated?

Nova Post waybill and locker data API

Screenshots

API surface

Track shipment by id

Get shipment detail

Calculate shipment tariff

Postomat locker open codes

Available parcel lockers

Courier vehicle coordinates

Division alarm status

Courier pickup order

Courier time intervals

Client profile

Favorite delivery addresses

Shipment payment status

Pay with loyalty points

List shipment promo codes

Sync shipment versions

Data categories

Where teams use this data

Marketplace waybill tracking

Locker and branch overlay

NovaPay and COD reconciliation

Courier pickup windows

Frequently asked questions

Related apps

Apps similar to Nova Post

More Transport apps

Careem Captain

Delhivery: Courier App

DiDi Driver: Drive & Earn Cash

Dostavista — работа курьером

Topics

Need this app's data API integrated?