Nova Poshta Premium — Nova Poshta for WooCommerce

Nova Poshta Premium for WooCommerce is a module that connects your store to Nova Poshta in 10 minutes. The customer picks a city and a branch right at checkout, the shipping cost is calculated using Nova Poshta’s live rate, and the waybill is created from the order screen or automatically — once the order reaches the status you choose.

The widget doesn’t just get added alongside — it replaces the address fields. Street, city, region and postcode are filled in from the chosen branch, so the customer has nothing to type by hand, and you’re left with a correct shipping address on the order.

The base version is free — branch selection, live rate, waybill creation and a shipment log. The Premium licence adds cash on delivery on the waybill, automatic status updates, return waybills, cash-on-delivery reconciliation and webhooks.

What the customer sees

At checkout, instead of the usual set of address fields, the customer sees a single block: a city field with suggestions (or a one-click list of popular cities) and a list of that city’s branches and parcel lockers. Once a branch is chosen, the shipping cost in the order summary is instantly recalculated using Nova Poshta’s rate.

The block works on both the classic checkout and Checkout Blocks: the choice is stored via the WooCommerce session, so both behave the same way. If the customer picks Nova Poshta but doesn’t select a branch, the order can’t be placed until they do.

What the admin gets

Every shipment sits in one log: waybill number with a tracking link, recipient, current status, cash-on-delivery amounts and money-transfer numbers.

The order screen shows exactly which branch the customer chose, plus a button to create the waybill — no need to go into your Nova Poshta account.

Settings — a single page

The module is added as a regular WooCommerce shipping method. All settings live on one page: API key, sender profile, pricing rules, widget appearance and waybill automation. The “Check connection” and “Test rate lookup” buttons show right away whether everything is set up correctly.

How it works, step by step

1. Paste in the API key from your Nova Poshta account and click “Check connection”.
2. Choose your city, branch and sender profile — waybills will be created from these.
3. At checkout, the customer picks a city and branch and sees the shipping cost at Nova Poshta’s rate.
4. The order stores the city, branch and delivery address, and a shipment draft appears in the log.
5. The waybill is created via a button on the order, or automatically once it reaches the status you chose.
6. Delivery statuses are updated from the Nova Poshta API (automatically on Premium, manually via a button on the free version).

What’s included in each licence

Free: city and branch selection at checkout (both classic and block checkout), rate calculation, replacing and auto-filling the address fields, manual and status-triggered waybill creation, shipment log, directory caching, key encryption.

Premium: cash on delivery (money transfer) on the waybill, automatic hourly status updates, one-click return waybills, cash-on-delivery reconciliation with amounts and transfer numbers, outbound webhooks on delivery events with an HMAC-SHA256 signature.

Technical requirements

• WordPress 6.2 or newer
• WooCommerce 7.0 or newer (HPOS-compatible)
• PHP 7.4 or newer
• A Nova Poshta API key from your account

Under the hood

The module works through the official Nova Poshta API (api.novaposhta.ua/v2.0). City and branch directories are stored in their own tables and refreshed on a schedule, so checkout never waits on an external request. The API key is stored encrypted in the database and is never shown back in the form. No third-party iframes, no swapped-out checkout templates — only standard WooCommerce hooks.

How to install

1. Download the archive and install it via “Plugins → Add New → Upload Plugin”.
2. Activate the plugin.
3. WooCommerce → Settings → Shipping → add the “Nova Poshta” method to the zone you need.
4. Paste in the API key, save, and fill in the “Ship from” block.

Version history

1.1.2 — fixed return-waybill creation: the request to Nova Poshta was going out without a return-reason subtype, and the branch was being placed into the field meant for the counterparty’s address — which made the button fail with an error. Now, before creating the waybill, the module asks the carrier whether a return is even possible for that waybill, and shows that exact answer (for example, a return isn’t available while the shipment hasn’t yet been handed over to Nova Poshta).

1.1.1 — a single order can no longer get two waybills: status-triggered auto-creation and the admin button (or two clicks in a row) could fire at the same time and create two real shipments at Nova Poshta. Waybill creation is now serialised, so the second call sees the waybill that already exists. The last licence check time is now stored in UTC — the status no longer shows “checked -1 days ago”.

1.1.0 — a 7-day Premium trial, started with a click: the key arrives by e-mail, no card required. A fresh install no longer switches anything on by itself — Premium features are visible in place, inactive, marked Pro with an explanation of what they do. A new “Webhooks” screen has appeared (WooCommerce → Nova Poshta → Webhooks): endpoints, an HMAC-SHA256 signing secret, event selection and a delivery log with retries — previously webhooks could only be set up by writing directly to the database. The licence key is no longer wiped by a plain “Save changes”. In the shipment log, the “Recipient” column now shows the customer, and the direction has moved to its own “To” column.

1.0.1 — API-based rate calculation is now an option, off by default: previously the “Fallback cost” was only ever a fallback and was always overridden by Nova Poshta’s rate. A zero cost no longer shows as “Free!” — the method is labelled “(cash on delivery)”, with the price shown as “carrier rates apply”. Free shipping from an order threshold works as before.

1.0.0 — first release: a branch-selection widget for classic checkout and Checkout Blocks, live rate, waybill creation, shipment log, status tracking, Premium licence.