Why Automate Delivery Through the API

Manually creating shipments through the Nova Poshta website takes 3–5 minutes per order. With 20 orders per day — that's an hour of routine work daily. The Nova Poshta API cuts this to seconds: order arrives → TTN created → tracking number sent to customer → statuses update automatically.

Additional benefits: minimizing manual address entry errors, automatic selection of the nearest branch, real delivery cost calculation in the cart.

Nova Poshta API v2 Overview

Nova Poshta API is a free REST API with JSON. You need an API key generated in your personal cabinet:

Personal Cabinet → Settings → Security → Generate API Key

Base URL: https://api.novaposhta.ua/v2.0/json/

All requests are POST with a JSON body:

{
  "apiKey": "your_api_key",
  "modelName": "ModelName",
  "calledMethod": "MethodName",
  "methodProperties": { ... }
}

Response always contains success (true/false), data (results array) and errors.

Searching Branches and Addresses

Getting the City List

{
  "modelName": "Address",
  "calledMethod": "getCities",
  "methodProperties": {
    "FindByString": "Odesa",
    "Limit": 20
  }
}

Returns an array of cities with fields Ref (unique identifier), Description (name), AreaDescription (region).

Finding Branches in a City

{
  "modelName": "AddressGeneral",
  "calledMethod": "getWarehouses",
  "methodProperties": {
    "CityRef": "city_identifier",
    "Limit": 50,
    "Page": 1
  }
}

Delivery Cost Calculation

Real-time calculation in the cart instead of a fixed price is a significant UX improvement:

{
  "modelName": "InternetDocument",
  "calledMethod": "getDocumentPrice",
  "methodProperties": {
    "CitySender": "sender_city_ref",
    "CityRecipient": "recipient_city_ref",
    "Weight": "1.5",
    "ServiceType": "WarehouseWarehouse",
    "Cost": "500",
    "CargoType": "Parcel",
    "SeatsAmount": "1"
  }
}

Response contains Cost (delivery cost in UAH) and CostRedelivery (return delivery cost for cash-on-delivery).

Creating a TTN (Waybill)

This is the most important method — it creates a shipment and returns a tracking number. The response includes IntDocNumber — the 14-digit tracking number, and Ref — the unique document identifier.

Tracking Shipment Statuses

{
  "modelName": "TrackingDocument",
  "calledMethod": "getStatusDocuments",
  "methodProperties": {
    "Documents": [
      { "DocumentNumber": "59000000000000", "Phone": "0671234567" }
    ]
  }
}

Key status codes: 1 — Created, 3 — In transit, 4 — Arrived at branch, 5 — Delivered, 6 — Return, 9 — Refused.

Webhooks for Automatic Updates

Instead of polling (checking status every N minutes) — subscribe to webhook notifications. Nova Poshta will send a POST request to your URL with every status change. Your handler updates the order status in the database and sends an SMS/email to the customer.

Common Errors and How to Avoid Them

"Required fields not filled" — check that all Ref fields are populated. Common cause: sender city Ref doesn't match the branch Ref.
"Invalid API key" — the key needs confirmation in the cabinet (SMS confirmation option).
Rate limiting — NP API has a limit of ~100 requests/minute per key. For bulk operations: use a queue with delays between requests.
Outdated address Refs — NP occasionally updates branch Refs. Cache addresses for maximum 24 hours, not indefinitely.
Date format — only dd.mm.YYYY, not ISO 8601.
Weight 0 — if weight is 0, the API returns an error. Set a minimum of 0.1 kg.

Integration Example: Laravel

Use the daaner/nova-poshta-api2 package or write a custom HTTP client using Laravel's HTTP Facade. The key is wrapping all API calls in a service class that handles authentication, error checking, and throws exceptions on API failures — keeping your controllers clean.

Conclusion

The Nova Poshta API is well-documented and stable enough for production use. The hardest part is understanding the Ref identifier system the first time. After that, delivery automation becomes a straightforward task.

We integrate the Nova Poshta API into any platform — WooCommerce, Laravel, custom solutions. Contact us and we'll estimate the scope of work for your project.

Nova Poshta API: Automating Delivery for Your Online Store