↑↓ selectEnter openEsc close

    1. Elbuz

    How to set up Nova Poshta delivery in your store

    5 min readUpdated

    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

    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”.

    1. Check that Nova Poshta is on in the “Carriers” block. In a new store it's already on, together with its three methods.
    2. Choose “Shipping cost” in the “Ukraine · Nova Poshta” block: “Nova Poshta tariff” or “Fixed price of the method”. The next section explains the difference.
    3. For the tariff, set “Sender city”: pick the region, then the city you ship parcels from.
    4. 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”.
    5. Click “Save”. The changes go to the store right away.
    The “Ukraine · Nova Poshta” block of the Delivery module with its shipping cost, sender city and API key fields
    1Shipping cost
    2Sender city: region and city
    3Nova Poshta API key (optional)
    4Geo zone
    1. Shipping cost — the Nova Poshta tariff, or the fixed price of the method.
    2. Sender city — where you ship parcels from; the tariff is calculated from this city.
    3. API key — not required; the field is there in case Nova Poshta limits requests without a key.
    4. 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”.

    The “Still to set up” card with the Nova Poshta sender city item
    1Sender city not selected
    1. 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”:

    SettingWhat the customer seesWho pays for delivery
    “Nova Poshta tariff” with “Sender city” setThe 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 0Your price, for example UAH 70The 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.

    The “Prices and options” block: table header and the three Nova Poshta rows
    1Price, branch row
    2Free from, parcel locker row
    3Up to, kg, courier row
    4Title for the customer, branch row
    1. Price — 0 means the carrier’s tariff, or the tariff itself if one is set up.
    2. Free from — delivery is free from this order sum; 0 turns it off.
    3. Up to, kg — a heavier cart does not get this method; 0 means no limit.
    4. 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.
    Checkout delivery address with the City and Branch fields and the open list of Nova Poshta branches
    1City field
    2Branch field
    3First branch in the list
    1. The customer picks the city from the suggestions as they type.
    2. Type a branch number or street to narrow the list.
    3. 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 wrongMessage
    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 seeWhyWhat 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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free