The Nova Poshta module in an Elbuz CMS store lets the customer pick a branch, parcel locker or courier from a list. The shipping price is yours or the Nova Poshta tariff.
When you need this:
- Customers mix up branches — an order with a nonexistent branch won't pass.
- Show the exact shipping cost — the tariff is calculated by cart weight once the customer picks a city.
- Heavy parcels — points that won't accept the weight aren't listed.
- Free delivery above a total — from that total, the customer sees “Free”.
Where to start: “Store settings” → “Delivery” section → “Delivery” card → “Ukraine · Nova Poshta” block.
What Nova Poshta delivery can do
- Three methods — to a branch, to a parcel locker, courier to the door. Each one is turned on separately.
- City, branch and street suggestions — from the Nova Poshta directory, so nobody types a pickup point address by hand.
- Nova Poshta tariff — a price by cart weight and the customer's city, from your sender city.
- Your price or “Carrier rates” — a fixed amount, or the customer pays for delivery on receipt.
- Free above a total and a weight limit for each method.
- The branch goes straight into the waybill (TTN) — Elbuz takes it from the order.
How to set up Nova Poshta
Where: “Store settings” → the “Delivery” section → the “Delivery” card. How the screen works in general — carriers, methods, order — is covered in “How to set up delivery in your store”.
- Check that Nova Poshta is on in the “Carriers” block. In a new store it's already on, together with its three methods.
- Choose “Shipping cost” in the “Ukraine · Nova Poshta” block: “Nova Poshta tariff” or “Fixed price of the method”. The next section explains the difference.
- For the tariff, set “Sender city”: pick the region, then the city you ship parcels from.
- Set the prices in the “Prices and options” block, in the “Nova Poshta — …” rows: “Price”, “Free from”, “Up to, kg” and, if needed, “Title for the buyer”.
- Click “Save”. The changes go to the store right away.
1
Shipping cost2
Sender city: region and city3
Nova Poshta API key (optional)4
Geo zone- Shipping cost — the Nova Poshta tariff, or the fixed price of the method.
- Sender city — where you ship parcels from; the tariff is calculated from this city.
- API key — not required; the field is there in case Nova Poshta limits requests without a key.
- Geo zone — limits Nova Poshta to the cities of the zone; “All zones” means the whole of Ukraine.
Leave “Nova Poshta API key (optional)” empty: you don't need a key.
“Geo zone” limits Nova Poshta to the cities of the zone, for example your region. The region comes from the city the customer picked; until a city is picked, only the country is checked. “All zones” means all of Ukraine.
Tariff chosen but no sender city? “Still to set up” on the right shows “Nova Poshta: sender city is not selected — the tariff is not calculated, the option price applies”.
1
Sender city not selected- Until the sender city is chosen, the customer sees the price of the method instead of the tariff.
Only a code field instead of two lists, and “The Nova Poshta directory is not loaded in Elbuz yet — paste the sender city code (Ref).”? Contact Elbuz support.
Nova Poshta shipping cost: tariff or your price
What the customer sees next to the method depends on “Shipping cost” and the method's “Price”:
| Setting | What the customer sees | Who pays for delivery |
|---|---|---|
| “Nova Poshta tariff” with “Sender city” set | The Nova Poshta price for their cart, as soon as they pick a city from the list. Before that — the method's “Price” | The customer pays you: the shipping amount is part of the order |
| “Fixed price of the method”, “Price” above 0 | Your price, for example UAH 70 | The customer pays you: the amount is part of the order |
| “Price” is 0 (no tariff) | “Carrier rates” | The customer pays Nova Poshta on receipt |
The tariff is calculated separately for the branch, the parcel locker and the courier. The weight is the total weight of the cart items, and the declared value is the item total. Cash on delivery isn't included in the calculation.
If Nova Poshta doesn't respond within 8 seconds, the customer sees the method's “Price” and checkout doesn't wait. The module doesn't recalculate the same cart and city for 10 minutes.
1
Price, branch row2
Free from, parcel locker row3
Up to, kg, courier row4
Title for the customer, branch row- Price — 0 means the carrier’s tariff, or the tariff itself if one is set up.
- Free from — delivery is free from this order sum; 0 turns it off.
- Up to, kg — a heavier cart does not get this method; 0 means no limit.
- Title for the customer — the name shown at checkout; empty means the standard one.
Free delivery above a total
“Free from” is the cart item total at which the customer sees “Free” instead of the price, including the tariff. 0 turns it off. The threshold is set for each method separately: you can make the parcel locker free from UAH 1,500 and keep the courier paid.
Item weight and “Up to, kg”
“Up to, kg” hides the method if the cart is heavier; 0 means no limit. For “to a parcel locker” the default is 20: a Nova Poshta parcel locker doesn't accept anything heavier. Stores set up earlier may have 0 there — enter 20.
The module also filters branches and parcel lockers on its own: the list shows only those that accept a parcel of that weight.
If items have no weight, the tariff is calculated as for 0.1 kg, and neither the pickup point filter nor “Up to, kg” works. Fill in the weight in the product cards.
What the customer sees at checkout
Method names at checkout: “Nova Poshta: to a branch”, “Nova Poshta: to a parcel locker”, “Nova Poshta: courier to the door” — or under your “Title for the buyer”.
- City — suggestions from the first letter, in Ukrainian or Russian. The type and region are shown next to the name, so two villages called Oleksandrivka can't be mixed up.
- Branch or Parcel locker — the customer enters a number (“12”) or a street. The list shows up to 30 points; in a big city, entering the number is faster.
- Courier — “Street” with suggestions for the streets of the chosen city; “House” is required, “Flat” isn't.
1
City field2
Branch field3
First branch in the list- The customer picks the city from the suggestions as they type.
- Type a branch number or street to narrow the list.
- Branches of the chosen city with their address; the customer can pick only from this list.
The order won't go through until the data matches the directory. The customer sees:
| What's wrong | Message |
|---|---|
| The city wasn't picked from the list, and no single match was found by name | “Pick the city from the list so we know where to deliver” |
| The city has no branches or parcel lockers | “Nova Poshta has no branches in this city: choose the courier or another city” (for a parcel locker — “…choose a branch or the courier”) |
| The branch isn't from the list | “Pick the branch from the list” or “Pick the parcel locker from the list” |
| Courier with no house number | “Enter the house number” |
Where the branch list comes from
The city and branch directory updates itself every night, there's nothing to upload. The list has only working branches and parcel lockers you can ship to. While an update runs, checkout uses the old list; if an update fails, the old list stays.
If the directory is unavailable, the customer types the city and branch by hand, and the store accepts the order without checking. Verify such an order before creating the waybill.
What goes into the order
- Address: for a branch or parcel locker — the pickup point name; for a courier — “street, house, flat N”.
- Country and region — “Ukraine” and the region of the chosen city. They're filled in automatically; the customer doesn't enter them.
- Shipping price — the one the customer saw; with “Carrier rates” — 0.
In Elbuz, the order arrives in “Customer order” documents with Nova Poshta as the delivery type. Elbuz fills the branch from checkout into the waybill form unless another one is chosen there, so you don't retype the address. How to create a waybill and track the parcel: Nova Poshta API in Elbuz; all parcels together — Parcel tracking.
Cash on delivery is a separate payment method: How to accept cash on delivery, in-store and invoice payments. The delivery module doesn't hide it for any Nova Poshta method.
API key: do you need one, and is it the same as in Elbuz
The store doesn't need a key: the directory, street suggestions and tariff work without one. The “Nova Poshta API key (optional)” field is only needed if Nova Poshta starts limiting requests without a key.
This is not the same key as in the Nova Poshta connection for waybills (“Token” in “External services and integrations”). Elbuz and the store keep them separately and don't take them from each other.
Want one key for everything? Enter the same key from your Nova Poshta business account in the store: Settings → Security → My API keys. Where to create it — Nova Poshta API in Elbuz.
Scenarios
Washing machines and fridges
Turn on “to a branch” and “courier to the door”, and turn off “to a parcel locker”. For a 60 kg parcel, the list keeps only branches that accept that weight, and the courier gets an address with the house and flat.
Smartphones and accessories
“Shipping cost” — “Fixed price of the method”. For “to a parcel locker”: “Price” — 0, “Free from” — 1500. For a cheap order, the customer pays Nova Poshta on receipt; from UAH 1,500, delivery is free.
Small home appliances
“Shipping cost” — “Nova Poshta tariff”, “Sender city” — your warehouse. The customer sees the shipping price for their cart before ordering, and it's added to the total right away.
Clothing and footwear
“to a branch” and “to a parcel locker” with “Price” 0, no tariff set up. The customer picks up wherever it's convenient and pays for delivery on receipt.
What to do when delivery doesn't work as expected
| What you see | Why | What to do |
|---|---|---|
| Nova Poshta isn't shown at checkout | The carrier or all its methods are off, the cart is heavier than “Up to, kg”, or the customer's city is outside the “Geo zone” | Check the switch in “Carriers”, the “Nova Poshta — …” rows in “Prices and options”, and “Geo zone” |
| Instead of the tariff — “Carrier rates” or your price | “Fixed price of the method” is chosen, “Sender city” isn't set, the customer hasn't picked a city from the list yet, or Nova Poshta didn't respond | Choose “Nova Poshta tariff” and the sender city, then save. Check on the site by picking a city from the suggestions |
| The tariff is suspiciously low | The items have no weight — 0.1 kg is used | Fill in the weight in the product cards |
| The customer can't find the branch or parcel locker they need | The point doesn't accept a parcel of that weight | This protects against the parcel being sent back. The customer should pick another point from the list or the courier |
| A new branch is missing, or city suggestions don't appear | The directory hasn't updated yet or is unavailable | A new branch appears after the nightly update. No suggestions for more than a day — contact Elbuz support |
FAQ
What happens if I turn Nova Poshta off?
Its methods disappear from checkout. Prices, names and the sender city are kept: turn it back on and everything is in place.
Does the store create the waybill itself?
No. The store only takes the branch or address. You create the waybill in Elbuz: Nova Poshta API in Elbuz.
I ship from two cities — which one do I set?
There is one sender city. Set the one most parcels ship from: the customer's tariff is calculated from it.
How do I rename a method, for example to “Pickup from Nova Poshta”?
Enter “Title for the buyer” in the method's row — separately for each site language. An empty field means the standard name.
How do I put Nova Poshta first in the delivery list?
Drag it to the top in the “Carriers” block. More: How to set up delivery in your store.
Where to find it and who has access
- Menu
- Directories → Operations → Store settings → “Delivery” → the “Delivery” card
- Access rights
- the “Store settings” window in group permissions
- Prepare
- the city you ship parcels from; the weight in the product cards
Related topics
- If you need to set up other carriers or the order of methods — How to set up delivery in your store.
- If an order has arrived and it's time to create the waybill — Nova Poshta API in Elbuz.
- If you have many parcels and need to see them together — Parcel tracking.
- If customers pay for goods on receipt — cash on delivery in the store.
