Nova Poshta Premium — a Nova Poshta module for OpenCart 2.3, 3.x and 4.x

Nova Poshta Premium is a module for OpenCart 3.x and 4.x that connects your store to Nova Poshta in 10 minutes. The customer picks a city and branch right in the cart, and the waybill is created automatically when you move the order to “Processing”. No third-party iframes, no rewriting the checkout, no daily copying of data into the Nova Poshta account.

The basic version is free. Download it from the official OpenCart marketplace: opencart.com/…/extension_id=48538. Premium features (cash on delivery, return waybills, auto-updating statuses, webhooks, multi-warehouse) are unlocked with a licence key — buy below.

Live demo

You can try the module hands-on before buying: open the demo store on OpenCart 4. Add any product to the cart and go to checkout — at the shipping step a “Nova Poshta delivery” block appears, with live city and branch search via the Nova Poshta API. Orders are test orders, and nothing needs to be paid (choose “Cash on delivery”).

What the customer sees

What the admin gets

How it works, step by step

1. The customer on the site chooses Nova Poshta as the shipping method, searches for a city, and picks a branch.
2. The order is created in your OC admin panel with the chosen branch saved against it.
3. You move the order to the trigger status (by default, “Processing”).
4. The module automatically calls the Nova Poshta API: it creates the recipient as a private individual (from your checkout — name and phone), then prints the waybill. The number is written to the order.
5. With Premium: it polls Nova Poshta hourly for the status of every active shipment, gets the payout number for cash-on-delivery orders, and sends a webhook to your CRM/ERP on every status change.

Pricing

2,490 UAH — a one-off purchase. The licence is perpetual: you pay once, updates and technical support are included in the price. One key covers one domain and its subdomains.

If you move the store to another domain, deactivate the licence on the old one and activate it on the new one yourself in your account.

The licence is perpetual — nothing expires or switches off. One key covers one domain; if you move the store, deactivate the licence on the old domain and activate it on the new one yourself.

One key covers two domains (production + staging). If you move the store, deactivate the licence on the old domain and activate it on the new one yourself, without contacting support.

Trial first, payment later. A fresh install is the free version: Pro doesn’t switch on by itself, and nothing turns off after a week either. When you want to look at Pro, click “Try Pro” in the module settings, enter an e-mail and get a 7-day key (also sent by e-mail). So you check cash-on-delivery reconciliation, return waybills and bulk operations on your own store before you buy — that’s exactly why refunds after payment are not offered.

Technical requirements

• OpenCart 4.0.2 – 4.1.x (4.2+ also works) — or a separate build for OpenCart 3.0.2 – 3.0.5.0
• PHP 8.1+ (tested on 8.5 — protection against new deprecation warnings inside JSON endpoints)
• MySQL 5.7+ / MariaDB 10.3+
• A Nova Poshta API key — free in your account: my.novaposhta.ua → Settings → Security → API
• One registered sender profile in the Nova Poshta business cabinet — most merchants already have one (without it, Nova Poshta doesn’t allow waybills to be created from any source)

Under the hood

• Native for OpenCart 4.x — PSR-4 namespaces, the events API, Twig. Not OCMOD, not XML mods. Compatible with future OC releases with no rewrite.
• The API key is encrypted in the database — XOR with a per-install secret derived from a wp-salt. If someone dumps the database, the key can’t be read in plain text.
• A city and branch cache with lazy refresh — a full weekly sync via cron, lazy loading of branches for requested cities (7-day TTL). Autocomplete in the checkout responds in 44 ms instead of 211 ms for a direct API call.
• A two-stage waybill creation: first Counterparty.save for the recipient (a PrivatePerson with a phone number in Nova Poshta’s format), then InternetDocument.save. Works for every sender type — private individual, sole proprietor, LLC.
• HMAC-signed webhooks with retries: 5/10/20/40 min exponential backoff, up to 4 attempts. sha256 signatures, an X-NP-Signature header.

How to install

1. Download nova_poshta_premium.ocmod.zip via Extensions → Installer in your OC admin panel. For OpenCart 3.0.x, use the nova-poshta-premium-oc3-1.2.8.ocmod.zip build (available in the product’s downloads).
2. Activate it in the list, then open the settings → click “Complete installation” (this creates the database tables, events and cron tasks).
3. Paste in the API key from your Nova Poshta account, click “Test connection” — you’ll see “Connection working”.
4. Choose your city and branch → load the sender profile → save.
5. Done — a block for choosing Nova Poshta delivery appears in the cart.
6. For Premium features: paste in the licence key from the e-mail after payment → “Activate licence”.

Version history

1.2.17 (OpenCart 4.x) / 1.3.1 (OpenCart 3.x) / 1.3.1 (OpenCart 2.3) — 14 August 2026

Fixed creating a return waybill: the request to Nova Poshta was sent without a return-reason subtype, and the branch was being placed in a field that expects the counterparty’s address — because of this, the “Return waybill” button failed with an error on every build. Now, before creating it, the module asks the carrier whether a return is possible for this waybill and shows exactly their answer (for example, that a return isn’t available yet because the shipment hasn’t been handed to Nova Poshta).

1.2.16 (OpenCart 4.x) / 1.2.8 (OpenCart 3.x) — 3 August 2026

Calculating cost via the Nova Poshta API is now a separate option and is disabled by default. Previously the cost field was only a fallback: as soon as the API key and sender city were configured, the cost in the cart was always overwritten by the carrier’s rate — stores where the recipient pays for delivery had no way to turn this off. The field has been renamed to “Delivery cost” — this is exactly what’s shown to the customer. In addition, a zero cost no longer looks like free delivery — the method is now labelled “(cash on delivery)”, and “at the carrier’s rates” is shown instead of “0 UAH”. Also fixed an empty placeholder that hung under the branch-selection block before a branch was chosen.

1.2.7 — 23 July 2026

Fixed a fatal error in the shipping-method calculation: getQuote() was loading a catalog model, localisation/geo_zone, that doesn’t exist in OpenCart 4.x, which meant the entire list of shipping methods failed to appear (“A shipping address is required”). The geo-zone check is now done with a direct query to zone_to_geo_zone, the same as stock methods. Also: the city/branch block now only appears after the “Nova Poshta” method is chosen (method first, then the fields), doesn’t conflict with other carriers’ widgets, and has a demo set of cities/branches for clickable testing with no API key.

1.2.5 — 20 July 2026

Fixed the tools in the module settings working before the first save: city search, the branch list, the test rate check and loading the sender profile now use the API key entered in the field. Previously they only read the already-saved key, while the “Test connection” button checked the entered one — because of this, “Key is valid” appeared right after pasting a key, while city search replied “Nothing found”. Now it’s enough to paste the key and search for a city right away.

1.2.4 — 17 July 2026

Fixed city search on stores where OpenCart runs on the PDO database driver (DB_DRIVER = pdo): the query failed with an SQL error, so the field showed “Nothing found” even though the key and module were fine. There was no issue on the mysqli driver. Branch selection wasn’t affected — which is exactly why this looked like an API-key problem.

1.2.3 — 17 July 2026

Fixed city search on hosting where the PHP mbstring extension isn’t enabled: the field showed “Nothing found” even though the API key was valid and branch selection worked. The mb_strtolower / mb_substr functions are now only called when available, with UTF-8-safe fallbacks. This applies to both the OpenCart 4.x and 3.x builds — nothing needs reconfiguring after the update.

1.2.2 — 9 July 2026

Minor admin-panel fixes and updated screenshots. No functional changes.

1.2.1 — 29 June 2026

A separate build for OpenCart 3.0.2 – 3.0.5.0 — a full port of the 4.x version (non-namespaced classes, OC3 events, a Bootstrap 3 admin panel). Code and documentation synced. No functional changes on the OpenCart 4.x line.

1.2.0 — 23 June 2026

Customisable checkout-block appearance: accent colour, corner rounding (0–28px) and theme (auto to match the store’s design / light / dark) — the block adapts to any OpenCart theme. Plus improvements to localisation and the cart picker.

1.1.0 — 24 May 2026

Production-ready release: a real licence client reconciling with catcode.com.ua, a product_slug check (a key from another product won’t activate this module), gating Premium features via License::isPro(), a 14-day offline grace period, plain-language localisation with no jargon, a merge fix in the save handler.

1.0.c–f — May 2026

Cash on delivery (BackwardDelivery + payout sync), return waybills via AdditionalServiceGeneral.save with the reason “refusal to receive”, Latin → Cyrillic transliteration of the recipient’s name (Nova Poshta doesn’t accept Latin script), phone-number normalisation into Nova Poshta’s format.

1.0.b — May 2026

City and branch cache: the np_cities + np_warehouses tables, a weekly syncCities cron, a lazy warehouse cache with a 7-day TTL. Warehouse selection sped up roughly 5x (211 ms → 44 ms) — autocomplete in the cart becomes instant.

1.0.a — May 2026

Actual waybill creation: setting up the Counterparty sender in the admin panel + a two-step createTTN (Counterparty.save → InternetDocument.save). Before this, it was only a draft stub.

0.7 — May 2026

First full MVP: an install hook creating database tables, a storefront picker in the cart, a draft waybill on a new order, an hourly status cron, a webhook system, API-key encryption via XOR with a per-install secret.