↑↓ selectEnter openEsc close

    1. Elbuz
    2. Delivery services in Elbuz

    Nova Poshta API in Elbuz: waybills, registries, returns and COD

    18 min readUpdated

    With one API key, Elbuz creates Nova Poshta waybills, tracks parcels every 10 minutes, builds registries, handles redirects and returns — no business account needed.

    When you need this:

    • Dozens of shipments a day — waybills from the order card, registry and labels from one window.
    • Parcels return from branches — you see whose storage is ending and text the customer.
    • Cash on delivery — you see picked-up parcels whose transfer is still on its way, and the amount.
    • Customer wants another branch — redirect or return from Elbuz at a known cost.

    Where to start: create an API key in Nova Poshta → enter it in Elbuz.

    What Nova Poshta can do in Elbuz

    • Waybills from orders — to a branch, parcel locker or address, one at a time, in bulk or automatically by order status; until the parcel is handed over, the waybill can be edited or deleted.
    • Parcel statuses — every 10 minutes, with the storage deadline, the non-delivery reason and the COD transfer; waybills from the Nova Poshta account are linked to orders.
    • Registry and courier — one document for all parcels of the day, printing the registry and labels, calling a courier for the parcels.
    • Redirect, change of details, return — with the cost calculated before you confirm, and an entry in the order log.
    • COD control — which parcels are waiting for a transfer and for what amount.
    • Customer notifications — SMS from the parcel register, an automatic SMS by delivery status, an AI answer to “where is my order”.
    • Protection against a dead key — after 10 failures in a row the connection is turned off and you get a notification.

    How to connect Nova Poshta: API key and settings

    Where to get a Nova Poshta API key

    The key gives Elbuz access to your Nova Poshta contract: waybills, registries, statuses.

    1. Sign in to the Nova Poshta business account.
    2. Open “Налаштування” (Settings) → the “Безпека” (Security) tab → the “Мої ключі API” (My API keys) block.
    3. Click “Створити ключ” (Create key), accept the API terms of use and copy the key.
    The key page in the Nova Poshta business account (Ukrainian interface): Settings, the “Security” tab, the “My API keys” block with the “Create key” button
    1“Security” tab
    2My API keys
    3Create key
    1. API keys live in the account settings, the “Security” tab.
    2. The keys you already have are listed here; the key in the picture is hidden.
    3. A new key — the “Create key” button; this is the key you enter in Elbuz.

    Nova Poshta publishes its API method reference at developers.novaposhta.ua; you don't need it to work in Elbuz.

    Where to enter the key in Elbuz

    Where: Account → System settings → “Other settings” → “External services and integrations” → “Delivery” group → the Nova Poshta record.

    1. Paste the key into the “Token” field.
    2. Turn on “Active”.
    3. In the “Sender” block, choose “Sender” and “Contact person” — the lists arrive from your Nova Poshta account right after you enter the key; the phone and email are filled in from the contact person.
    4. In the same block, choose the “Region”, “City” and “Branch” you ship parcels from.
    5. If you have Nova Poshta's “Payment Control” service, turn on the “Payment Control Service” switch — it becomes the default for new waybills.
    Nova Poshta connection form with the token, the Active switch and the Sender block
    1Token
    2Sender and Contact person
    3Region, City and Branch of the sender
    4Payment Control Service switch
    1. Token — the Nova Poshta API key, shown masked.
    2. Sender and Contact person — chosen once and used for all waybills.
    3. Region, City and Branch — where the sender hands parcels over.
    4. Payment Control Service — switch for the cash-on-delivery control service.

    The form has no “Save” button: each field change is saved at once. The key in the “Token” field isn't shown: if it's saved, the field shows dots. An empty field doesn't erase the key; to replace the key, type the new one over it.

    The key isn't validated when saved. On the first connection, a wrong key shows up as empty “Sender” and “Contact person” lists. If you replace a working key with a wrong one, the lists keep the old values and the operation log shows “API Novapost error”. Copy the key from the account again, without spaces.

    You choose the sender and contact person once: the waybill form and bulk creation fill them in automatically. You can change them in the form of a single waybill.

    City and branch directories

    Elbuz updates Nova Poshta regions, cities, branches and parcel lockers itself once a day at night; the “Service directories” block in the same form shows how many records each directory has and when it was updated. “Update directories” starts an update right away — “Updating directories... this may take a couple of minutes”.

    If the update fails, you'll see “Directory update error:” with the reason, and the directory stays as it was yesterday — nothing is erased. A branch that opened today appears in the lists after the nightly update or a manual one.

    When Elbuz turns Nova Poshta off by itself

    If Nova Poshta rejects the key 10 times in a row — expired, deleted in the account — Elbuz turns off “Active” for the connection. The account owner gets an “Integration disabled” notification with Nova Poshta's response and the advice “Update the API key in the integration settings and turn it back on.”

    Only key rejections count: connection failures or Nova Poshta maintenance don't turn the connection off. Every request to Nova Poshta with this key counts a failure — status checks, user actions — so the connection is turned off after 10 key failures in a row, sometimes sooner than after 10 check runs.

    If there's nothing to track, the status check doesn't contact Nova Poshta. One successful response resets the counter.

    While the connection is off, parcel statuses aren't updated, waybills aren't created, and the Nova Poshta action buttons disappear from “Shipments”. To restore it, create a new key in the account, enter it in “Token” and turn on “Active”.

    How to create a Nova Poshta waybill from an order

    The general procedure for all carriers is in how to create a waybill from an order.

    Where: order card → “Delivery” → “Create waybill”.

    What the form fills in and what to check

    FieldWhat's there at onceWhat to check
    “Sender”, “Contact person”, sender city and branchfrom the connection settingscan be changed for a single shipment
    Recipient “Last name”, “First name”, “Middle name”, “Phone”the customer's details from the orderif someone else picks it up, correct them here
    Recipient “City”, “Branch”the branch the customer chose on the site; the city is matched by name against the directorythe fields may be empty if the name didn't match — the waybill still goes to the customer's branch
    “Shipment description”the product category, or the list of products if there's noneno more than 120 characters go to Nova Poshta
    “Total weight, kg”each product's weight × quantity, summedno weight — 2 kg goes into the waybill
    “Return delivery (recipient)”“Money” for the order amount if unpaid, “Not required” if paidpaid by card but payment not marked — set “Not required”
    “Delivery payer”“Recipient”delivery at your expense — “Sender”; “Third party” — only with the payer's “EDRPOU / RNOKPP code”
    Recipient: “Private person” / “Organization”“Private person”“Organization” requires the “EDRPOU / RNOKPP code”; the full name is its contact person
    “Delivery payment method”“Cash”“Cashless payment” — if you pay under a contract
    Waybill creation form for Nova Poshta
    1Cash on delivery (recipient) — Money
    2Payment Control Service
    3Payer for delivery
    1. Cash on delivery (recipient) is set to Money with the order amount.
    2. The Payment Control Service switch is off.
    3. The payer for delivery is chosen here: recipient, sender or third party.

    Branch, parcel locker or address

    “Shipping method” defaults to “Branch”. The “Parcel locker” option in the switch is inactive: you choose a locker in the branch list, and Elbuz sends Nova Poshta a 20×20×10 cm package. Elbuz doesn't check the locker's weight and size limits.

    “Address” is courier delivery to the door: instead of a branch you get “Street”, “House”, “Apartment” and “Address comment (optional)”; street and house are required.

    Elbuz looks up the street by name in the Nova Poshta directory for the recipient's city. If it isn't found, the waybill isn't created, and the “Warning” window shows “Error: Street not found in the city: ‹street›”. Enter the name without “вул.” (St.).

    What happens after “Create waybill”

    1. Elbuz checks the right to the waybill creation window and the required fields. If data is missing, a “Warning” appears with the field name, for example “empty Sender - Contact person”; the waybill isn't created and no money is charged.
    2. Elbuz registers the recipient with Nova Poshta and creates an express waybill with today as the shipping date.
    3. The number goes into the order's “Delivery service: number” field, and the window closes with “Waybill created, No.‹number›”. The “Create waybill” link disappears from the card. If the delivery type has a “Tracking link”, the tracking link is saved to the order too.
    4. Clicking again gives “Waybill already exists: ‹number› — skipped.”
    5. If Nova Poshta refuses, the “Warning” window shows its text, and the order stays without a number.
    The waybill is created at once, without confirmation, and is charged by Nova Poshta. Delete it before handover (editing and deleting); after that — only a return. If the waybill was deleted in the Nova Poshta account, the number stays in the order: to create a new one, clear “Delivery service: number” in “More fields”.

    How to edit or delete a waybill

    Until Nova Poshta accepts the parcel — the waybill is in the “Created” state — you can edit or delete it from Elbuz. “View waybill” in the order card then opens the same form with the note “The waybill has not been handed over to Nova Poshta yet: you can edit and save it, or delete it.”

    Waybill edit window with the Save changes and Delete waybill buttons at the bottom
    1Save changes
    2Delete waybill
    1. Save changes — stores the edited waybill data while it has not yet been handed over to Nova Poshta.
    2. Delete waybill — removes the waybill number from the order.
    • “Save changes” sends the form to Nova Poshta again; the waybill number stays the same: “Changes saved to the Nova Poshta waybill”.
    • “Delete waybill”, after confirmation, deletes the waybill in Nova Poshta and clears the order: the number and parcel state disappear, and you see “Waybill deleted. You can ship the order again.”

    Both actions are written to the order history and require the right to the “Delivery waybill creation” window. You can also delete it in “Shipments” — for a parcel in the “Created” state.

    After handover the form only shows the waybill; the recipient and payer are changed with “Change waybill details”.

    Waybills in bulk, automatically and from the Nova Poshta account

    Waybills in bulk

    “Create waybill (shipping)” in the order list creates waybills for all selected orders without a form.

    You don't need to open each order's form: the sender comes from the connection, the weight is products × quantity, the description is the category or the product list, the rest is as in the table above.

    The delivery method comes from the order: for branch delivery, the branch the customer chose. For address delivery, the bulk run takes the street and house only from a saved waybill form; without it the row shows “empty Recipient - Street”. If something was changed in the order's form, the values saved there are used.

    Orders that already have a waybill are skipped with a red row “Waybill already exists: ‹number› — skipped.” More: waybills in bulk.

    A waybill by itself when an order moves to a status

    Elbuz can create waybills without any clicks. In the Nova Poshta connection, choose a status in “Create a waybill automatically when an order moves to status”, for example “Picked”. The default is “— do not create —”.

    Sender block and the automatic waybill creation field with its hint
    1Sender
    2Automatic creation status
    3Hint under the field
    1. Sender — automatic creation does not work without it.
    2. Create a waybill automatically — set to «do not create».
    3. The hint explains the 10-minute cycle.

    Every 10 minutes Elbuz picks customer orders in this status with Nova Poshta delivery, created in the last 7 days and still without a waybill — up to 20 at a time. It creates waybills for them the same way as in bulk. The order history shows “Waybill ‹number› created automatically”.

    Without a selected sender auto-creation doesn't work, and the form warns: “Choose the sender above — without it waybills are not created automatically.” If Nova Poshta refuses, the order history shows “Waybill not created automatically: ‹reason›. Next attempt in an hour.” Fix the order data — the next attempt runs by itself.

    Each automatic waybill is a paid Nova Poshta service, and it's created without a confirmation. Choose a status that orders move to only when they're really ready to ship.

    Waybills created in the Nova Poshta account

    If some waybills are created in the Nova Poshta account, Elbuz shows the ones that aren't in any order. “Shipments” window menu → “Nova Poshta account waybills”: choose a period — the last 14 days by default, no longer than 31 days — and click “Show”.

    The list shows the number, date, state, shipping cost, COD amount and registry number; the recipient's name and phone aren't there. “Link to order” → “Elbuz order number” → confirmation → “Waybill ‹number› linked: its status now updates automatically.”

    You can link only to a customer order without a waybill; the order's delivery type becomes “Nova Poshta”, and the history shows “Nova Poshta account waybill ‹number› linked”. The list is visible to staff who can see all orders: the account holds the waybills of every manager.

    Panel listing waybills created in the Nova Poshta account that are not yet linked to Elbuz orders
    1Period and Show
    2Waybills missing from Elbuz
    3Link to order (do not press)
    1. Set the From and To dates and press Show to read the account waybills.
    2. This line counts the account waybills that have no matching Elbuz order.
    3. The icon links a waybill to an order; it was not pressed for this frame.

    Cash on delivery and “Payment Control”

    SwitchWhat goes to Nova Poshta
    off, “Return delivery (recipient)” — “Money”cash on delivery: return delivery of money for the amount in the “Amount” field, paid by the recipient
    on, “Money”the “Payment Control” service for the same amount
    “Not required” — with or without the switcha parcel without COD

    “Payment Control” works only together with “Money”: for a paid order, just set “Not required”.

    How to see that the transfer has arrived

    Nova Poshta marks a picked-up parcel with one of three codes: 9 — received, 10 — received, the transfer will arrive within a day, 11 — transfer paid out. Elbuz keeps tracking a parcel with code 10 until 11 arrives.

    • The “Cash on delivery” column in “Shipments” shows the amount and a mark: “transfer received”, “transfer pending” or “not collected” — for refusals.
    • The “COD transfer pending” quick filter keeps parcels that were picked up while the money hasn't arrived yet.
    • The “COD transfers on the way” and “COD in active parcels” tiles show the amounts.
    Shipments filtered by COD transfer pending, with the Cash on delivery column showing transfer pending badges
    1COD transfers on the way tile
    2transfer pending badge
    3COD transfer pending filter
    1. COD transfers on the way — the total of cash-on-delivery amounts that Nova Poshta has not yet paid out.
    2. The transfer pending badge — the parcel is received and the COD payout is still on its way.
    3. The COD transfer pending filter — shows only parcels waiting for the payout.

    The order's payment status becomes “Paid” by itself on code 11 if the order is in a checked status — see automatic status changes.

    How Elbuz tracks parcels and changes order statuses

    Elbuz asks Nova Poshta for the parcel states every 10 minutes — on the schedule of the “Checking delivery status” task. “Refresh statuses” runs a check right away.

    The result goes to the “Shipments” window: where the parcel is, at which branch, until what day it's stored, how much delivery cost, whether the transfer has arrived, why it wasn't delivered. The window's filters, columns and tiles are covered in Shipments: all parcels in one register.

    Shipments window with one Nova Poshta parcel selected and the operation buttons above the list
    1Status tiles that double as quick filters
    2Statistics tiles
    3Nova Poshta operation buttons
    1. Quick filters narrow the list to parcels at a pickup point, in transit, refused and so on.
    2. Statistics tiles show how many parcels and how much cash on delivery are on the way.
    3. With a Nova Poshta row selected, the operation buttons for registry, labels, redirect, edit and return appear above the list.
    Parcels are always updated, but the order's own status changes only in checked statuses and by the codes in the status windows
    noyesnoyesnoyesEvery 10 minutes or with “Refreshstatuses”Up to 100 waybills per connection —the longest unchecked firstDid Nova Poshta accept the APIkey?The failure is counted — 10 in a rowand the connection is disabledParcel state, branch, storagedeadline, COD — into the order andthe “Shipments” registerIs the order status checked in theconnection?The order status doesn't changeIs the Nova Poshta code in thestatus windows?Order, delivery and paymentstatuses change, an entry goes tothe log“Document: update” flows fire —SMS, emails
    • Action or result
    • Decision: the path depends on the answer
    • Key step
    • Elbuz tracks Nova Poshta waybills in orders from the last 60 days, and in orders with checked statuses — with no date limit. Polling stops on a final code: 9 — received, 11 — transfer paid out, 106 — received and a return delivery created, 2 — deleted, 124 — destroyed. Refusals aren't final: Elbuz keeps tracking them.
    • Up to 100 waybills per run, the longest unchecked first.
    • A number entered in the order by hand (the waybill was created in the Nova Poshta account) is tracked too — if the order's delivery type is “Nova Poshta”.
    • The shipping cost calculated by Nova Poshta appears in the “Shipping cost” column; it isn't written into the order itself when the waybill is created.
    • Elbuz doesn't store the recipient's name, phone or address from Nova Poshta's response.

    How to set up automatic order status changes

    Elbuz changes the order status, delivery status and payment status only in orders whose status is checked in the connection. Other parcels are simply tracked.

    1. In the connection form, under “Order statuses for which to check the parcel status with the delivery service”, check the statuses in which orders wait for delivery, e.g. “Shipped” and “Delivered”. Also check the statuses Elbuz moves orders to: an unchecked “Delivered” order won't move to “Done” or get “Paid”.
    2. In the “Notification settings” block, open “Order statuses”, “Delivery statuses” and “Payment statuses” one by one. On the first opening, Elbuz fills the Nova Poshta codes into the “Code (name) on site (API)” column itself.
    3. Check the codes or add your own, separated by commas.
    Until a status window has been opened at least once, it has no codes — and order statuses don't change, even though parcels in “Shipments” are updated.
    Nova Poshta codes Elbuz fills in itself
    WindowYour statusNova Poshta codes
    “Order statuses”“Delivered”7, 8 — arrived at a branch or parcel locker
    “Order statuses”“Done”9, 10, 11 — received
    “Delivery statuses”“On the way”4, 41, 5, 6
    “Delivery statuses”“At destination”7, 8
    “Delivery statuses”“Delivered”9, 10, 11
    “Delivery statuses”“Refused”102, 103
    “Payment statuses”“Paid”11 — transfer paid out
    Delivery statuses window with Nova Poshta status codes filled in
    1Code (name) on site (API) column
    2At destination row with codes 7,8
    1. The Code (name) on site (API) column holds the Nova Poshta status codes mapped to each delivery status.
    2. The At destination row maps codes 7 and 8.

    When the status changes, the order's operation log gets “Delivery status has changed: ‹code› ‹Nova Poshta text› #‹waybill number›”, and your automatic rules on the “Document: update” event fire — for example, an arrival SMS.

    Registry, labels and courier pickup

    A registry is one document for all the parcels you hand over at a branch or to a courier, instead of a separate waybill for each. Elbuz builds it in the Nova Poshta account.

    Where: Directories → Documents → Shipments → select rows → “Add to Nova Poshta registry”.

    1. Filter by “Not handed over” — parcels not yet handed over.
    2. Select the rows you need and click “Add to Nova Poshta registry”.
    3. In the “Registry” field, choose “New registry for today” or an open registry that hasn't been printed yet.
    4. Click “Add”. Elbuz responds with “Registry ‹number›: waybills added — ‹count›” and lists the waybills Nova Poshta didn't accept, with the reason.
    5. Click “Print registry” and print two copies, then one of the label buttons — “Labels on A4 (6 per sheet, 85×85)” or “Labels for thermal printer 100×100” — to stick a label on each parcel.
    Drawer «Add to Nova Poshta registry» with the selected waybill and the Registry field
    1Selected waybill numbers
    2Registry field
    3Add button
    1. Selected waybill numbers that will go into the registry.
    2. Registry field — «New registry for today» by default.
    3. Add button — puts the waybills into the registry (not pressed).

    The registry number appears in the “NP registry” column and in the order log.

    Nova Poshta sets the registry rules: one sender for all waybills; a waybill in only one registry; nothing can be added after printing; a parcel already scanned at a branch can't be added. Elbuz looks up the waybill in the key's account, so a waybill from another account won't get in.

    Printing waybills, labels and registries

    ButtonWhat's printed
    “Print” in “View waybill”, “Print waybill” in “Shipments”an A4 express waybill form; with several Nova Poshta waybills selected — all forms in one PDF
    “Print labels” in “Shipments” → “Labels on A4 (6 per sheet, 85×85)”85×85 mm stickers, 6 per A4 sheet — for a regular printer
    “Print labels” → “Labels for thermal printer 100×100”100×100 mm labels for a thermal printer (Zebra)
    “Print registry”the handover registry

    The PDF opens from Elbuz in a new tab: you don't need to sign in to the Nova Poshta account, and the API key isn't in the URL. If Nova Poshta refuses to print, the same tab shows the reason.

    A red pop-up instead of a tab means the request never reached Nova Poshta. Causes: no connection key or waybill number; “You have no access to this shipment.” — no right, or the order is outside your “Data scope”; “The action failed. Please try again.” — a connection failure.

    Calling a courier for parcels

    You call a Nova Poshta courier to collect parcels from your address in “Shipments”. For a single parcel you can also call one from the waybill window in the order card — the “Courier pickup” block under the form; for several parcels, use “Shipments”. The “Courier call” service is enabled by your Nova Poshta account manager.

    1. Select the parcels and click “Call a courier”.
    2. “Pickup date” is the nearest working day: today if it's before 16:00, otherwise the next day; weekends move to Monday.
    3. “Time slot” lists Nova Poshta's free slots; “Sender address” comes from your account; “Planned weight, kg” is the total weight of the selected waybills.
    4. “Call” → “Courier called, request ‹number›”. Waybills Nova Poshta didn't accept for the request are listed with the reason.
    Call a courier panel for two selected waybills
    1Pickup date
    2Time slot
    3Sender address
    4Planned weight
    5Call
    1. Choose the day the courier should come.
    2. Pick one of the time slots offered by Nova Poshta.
    3. Select the sender address the parcels are collected from.
    4. Enter the estimated total weight of the selected parcels.
    5. Call places the courier request; it was not pressed.

    Accepted waybills get an entry in the order history. No free time slots — choose another day; no addresses — add a pickup address in the Nova Poshta account.

    Window menu → “Courier calls” shows requests for the last 7 days and the “Cancel call” button. If less than an hour is left before the slot ends and you pay by bank transfer, cancellation is charged — UAH 350. The list and cancellation are available to staff who can see all orders: requests are shared by the whole account.

    Registry list and disbanding

    A Nova Poshta registry is shared by the whole account. Staff with a restricted “Data scope” don't see “Nova Poshta registries” and get only “New registry for today” when adding. Printing another person's registry is refused: “Nova Poshta registries are managed by staff who can see all orders: a registry holds waybills of the whole account.”

    “Shipments” window menu → “Nova Poshta registries” shows the account's registries: number, date, a “printed” or “open” mark. Here you can also print and “Disband”: “Disband registry ‹number›? The waybills stay and can be added to another registry.”

    List of Nova Poshta registries with open and printed badges
    1Open registry
    2Printed registry
    3Disband button
    1. Open registry — waybills can still be added.
    2. Printed registry — no more waybills can be added.
    3. Disband button — dissolves the registry (not pressed).

    Redirecting, changing details and returning a parcel

    Three actions for a parcel on its way or at a branch — without the Nova Poshta account. Select a row in “Shipments”, and “Redirect”, “Change waybill details” and “Return to sender” appear above the list. Whether an action is possible now is up to Nova Poshta: Elbuz asks first and shows its answer if not.

    Redirects and returns are paid Nova Poshta services at its rates. You can't cancel a request from Elbuz: after “Request…” it's already with Nova Poshta. So click “Calculate” first — it's in the redirect and return panels; changing details has no calculation.

    Redirecting a Nova Poshta parcel to another branch

    The top of the panel shows where the parcel is going now and to whom. Then:

    1. In the “City” field, start typing the name — from two letters — and choose the city, then the “Branch”.
    2. Set “Who pays” (“Recipient” or “Sender (us)”), the “Payment method” and, if needed, a “Note for the carrier”.
    3. “Calculate” shows the “Cost” and “Estimated delivery” — so you know what the redirect costs before you request it.
    4. “Request redirect” → confirmation “Redirect the parcel to "‹branch›"?” → “Redirect request created: ‹number›”.
    Redirect panel for an in-transit Nova Poshta parcel with the new city and pickup point chosen and the calculated cost
    1Current destination
    2New city and pickup point
    3Calculated cost
    4Request redirect (do not press)
    1. The "Now" line shows where the parcel is heading at the moment.
    2. Pick the new city and pickup point here.
    3. After Calculate, the panel shows the redirect cost and estimated delivery date.
    4. Request redirect creates the request at Nova Poshta; it was not pressed for this frame.

    The branch in the order card doesn't change — the request is written to the order log: “Redirect requested for waybill ‹number›, request ‹number›”.

    Changing waybill details

    “Change waybill details” opens what Nova Poshta allows you to change for this particular parcel: “Recipient name” and “Recipient phone”, “Who pays” and “Payment method”. If nothing is allowed — “The carrier does not allow changing this waybill.” “Save changes” → “Send changes of waybill ‹number› to the carrier?” → “Change request created: ‹number›”.

    Returning a parcel to the sender

    1. “Return to” — the return address Nova Poshta offers for your account.
    2. “Reason” and “Reason details” — from Nova Poshta's list.
    3. “Payment method”: “Cash”, or “Bank transfer” if Nova Poshta allows it; a “Note for the carrier” if needed.
    4. “Calculate” — the return price and date.
    5. “Request return” → “Return waybill ‹number› to sender? This is a paid service at the carrier rate.” → “Return request created: ‹number›”.
    Return to sender panel with reason selected and the calculated cost
    1Return to
    2Reason
    3Calculated cost
    4Request return
    1. Return to is the Nova Poshta branch the parcel goes back to.
    2. Reason and reason details are taken from the carrier's list.
    3. After Calculate, the cost of the return appears.
    4. Request return submits the request to Nova Poshta; it was not pressed.

    The order log gets “Return to sender requested for waybill ‹number›, request ‹number›”. The return waybill number appears in “Shipments” in the “Return waybill” column after one of the next status checks. The column is hidden by default — turn it on in the window menu → “Column settings”.

    How to notify the customer about a parcel

    SMS to the recipient manually

    In “Shipments”, “SMS to recipient” above the list or the row's SMS icon opens the same window as “Send” → SMS in the order card. The phone comes from the order's delivery phone, or from the customer card if empty — check it, and add the waybill number to the text. This requires a connected SMS service (how to connect).

    The “Storage ending” filter keeps the parcels it's time to remind about — at a branch, with 2 days or less before the return.

    Automatic SMS when a parcel arrives

    Elbuz can send an SMS by itself when Nova Poshta reports that the parcel is at the branch. This needs an automatic rule (order list → header menu → “Automatic rules”):

    • event — “Document: update”;
    • condition — “Delivery status” equals “At destination”;
    • command — “Send SMS” with a text about the branch and the waybill number.

    It fires if the order is in a checked status and codes 7, 8 are in “Delivery statuses” (setup). One order gets this SMS once.

    The condition “Delivery status does not equal Initial value” doesn't fit here: it's checked only when a person saves the order, while the status from Nova Poshta arrives without a save — and no SMS goes out. More about conditions: SMS by status.
    Every 32 minutes Elbuz itself checks the automatic rules against unposted orders from the last 30 days — up to 300 of the newest. A new “delivery status equals …” rule will, on its first such run, also text customers whose parcels have been in that status for a long time.

    Where is my order: the AI answer and “Tickets”

    • AI support answers the customer's “where is my order” in chat, a messenger or email: parcel state, branch, expected date, storage deadline. More: parcel status in AI.
    • Proactive messages: “arrived at the branch” and a reminder before the return — customer notifications.
    • “Tickets” for the manager on problem parcels — “parcel is waiting at the branch, not picked up”, “parcel refused / returning to sender”, “cash on delivery not received after delivery”, “parcel stuck in transit — no movement”. Off by default; nothing is sent to the customer: problem orders.
    • AI changes the Nova Poshta branch based on the customer's words: branch change. The mode is off by default. AI can recreate a waybill in the “Created” state only with “May recreate the waybill” on — it then deletes the old waybill via the API; without permission it hands the ticket over to an agent.

    What stays in the Nova Poshta account

    Day-to-day parcel work happens in Elbuz. You'll need the Nova Poshta account for these actions:

    ActionWhat to do
    Extend storagein the account; Elbuz shows until what day the parcel is stored
    Redirect to an address, return to another branch or addressin the account; from Elbuz — redirect to a branch and return to the address from your account
    Switch COD to a card transfer, change the courier delivery slot for the recipient, cancel a return or redirect requestin the account
    Delete a waybill Nova Poshta has already acceptednowhere — the parcel is returned to the sender (return)
    Documents, pallets, tyres; packages of different sizesin the account; from Elbuz — a parcel or cargo with a total weight and number of packages

    Scenarios

    First connection

    What to do. Create a key in the account, enter it in “Token”, turn on “Active”, choose the sender's city and branch, check the “Shipped” and “Delivered” statuses and open the three status windows.

    What you get. Within 10 minutes (or right after “Refresh statuses”), parcel statuses for the last 60 days start appearing in “Shipments” — 100 waybills per run. Orders in “Shipped” move to “Delivered” by themselves, and then to “Done”.

    Daily dispatch

    What to do. Select orders in the list and choose “Create waybill (shipping)”, then in “Shipments” filter by “Not handed over”, select all, “Add to Nova Poshta registry” → “New registry for today” → “Add”, then “Print registry” and “Print labels”. If a courier collects the parcels — “Call a courier” for the same rows.

    What you get. One registry in two copies and a label on each parcel; the registry number is in every order, and the courier comes in the chosen slot.

    Waybills without clicks

    What to do. In the Nova Poshta connection, choose the sender, and for auto-creation, the “Picked” status.

    What you get. As soon as the warehouse moves an order to “Picked”, a waybill number appears in it within 10 minutes; Nova Poshta refusals are visible in the order history.

    The customer asks for another branch, the parcel is already on its way

    What to do. “Shipments” → row → “Redirect”, choose the city and branch, “Calculate”, tell the customer the price, “Request redirect”.

    What you get. A request at Nova Poshta and an entry in the order log; the new branch appears in the “Pickup point” column after a status check.

    A parcel is waiting and will go back soon

    What to do. The “Storage ending” filter → “SMS to recipient”.

    What you get. The customer gets a reminder while the parcel can still be picked up; storage is extended in the Nova Poshta account.

    Weekly COD control

    What to do. The “COD transfer pending” filter and the “COD transfers on the way” tile; in “Tickets”, turn on the “cash on delivery not received after delivery” problem.

    What you get. You see the amount on its way, and orders where the money hasn't arrived within 5 days reach the manager as separate tickets.

    What to do when something goes wrong

    Common problems
    What you seeWhyWhat to do
    “The delivery service is not connected: fill in its API settings (Settings -> External API services).” when opening the waybill form; in bulk — “empty - API token” The key isn't entered or “Active” is off, including after automatic shutdown Enter the key and turn on “Active” (where to enter the key)
    An “Integration disabled” notification Nova Poshta rejected the key 10 times in a row Create a new key in the account, enter it in “Token”, turn on “Active” (automatic shutdown)
    “empty Sender - Sender” (or “- Contact person”, “- City”, “- Branch”) The sender, contact person or dispatch branch isn't selected in the Nova Poshta connection Choose them in the connection's “Sender” block — after that every waybill fills them in (where to enter the key)
    The “Sender” and “Contact person” lists in the connection are empty Nova Poshta didn't accept the key Copy the key from the account again and enter it in “Token” (API key)
    “Error: Street not found in the city: ‹street›” There's no street with that name in the Nova Poshta directory for the recipient's city Enter the street name without “вул.” and abbreviations, as Nova Poshta spells it (address delivery)
    The recipient's city and branch are empty in the waybill form The city or branch name in the order didn't match the Nova Poshta directory Choose the city and branch in the form manually (directories)
    The waybill was deleted in the account, but “Create waybill” isn't in the card The deleted waybill's number stayed in the order Clear “Delivery service: number” in “More fields” (after creation)
    “‹number›: the waybill is not in the Nova Poshta account of this API key (created in another account or deleted).” when adding to a registry The waybill was created in another Nova Poshta account, not the one whose key is in Elbuz Add it to a registry in the account where it was created (registry)
    “Nova Poshta registries are managed by staff who can see all orders: a registry holds waybills of the whole account.” Your “Data scope” is restricted Add waybills to a new registry; other people's registries are printed by staff with access to all orders (registry list)
    “The carrier does not allow changing this waybill.” At this stage Nova Poshta doesn't accept changes Try a redirect or use the Nova Poshta account (parcel actions)
    “The parcel has already been handed over to Nova Poshta, so the waybill can no longer be edited or deleted.” Nova Poshta has already accepted the parcel Change the recipient or payer with “Change waybill details”, return the parcel with “Return to sender” (parcel actions)
    “The “Courier call” service is enabled by your Nova Poshta account manager…” Courier pickup isn't enabled in your contract Contact your Nova Poshta account manager (calling a courier)
    “Waybill not created automatically: ‹reason›. Next attempt in an hour.” in the order history Nova Poshta refused or the order is missing data Fix the order data — the retry runs by itself (auto-creation)
    Parcels are updated, but the order status doesn't change The order status isn't checked in the connection, or the status windows haven't been opened yet Check the statuses and open the three status windows (automatic status changes)
    “Directory update error:” and a reason The directory is unavailable right now; the previous version stays Try “Update directories” later or wait for the nightly update (directories)

    FAQ

    How much does the Nova Poshta integration cost?

    Elbuz charges nothing for waybills, statuses or parcel actions. You pay Nova Poshta for waybills, redirects and returns at its rates, and the SMS service for SMS.

    Does Elbuz see waybills created in the Nova Poshta account?

    Yes: the “Shipments” menu → “Nova Poshta account waybills” shows the ones that aren't in orders and links them to an order (account waybills). After linking, the parcel is tracked like one created in Elbuz.

    Why is the status in Elbuz behind the Nova Poshta website?

    Elbuz asks Nova Poshta every 10 minutes and takes up to 100 waybills per run. To update now, click “Refresh statuses” in “Shipments”.

    How long does Elbuz track a parcel?

    Until a final Nova Poshta code — 9, 11, 106, deleted or destroyed. Orders in unchecked statuses — up to 60 days from creation, in checked ones — with no date limit. A parcel with code 10 is tracked further until the transfer arrives.

    The key in the form shows as dots — is it saved?

    Yes: the “Token” field shows dots only if the key is saved. An empty field doesn't erase the key; to replace the key, type the new one over it.

    Can I cancel a waybill from Elbuz?

    Yes, until Nova Poshta accepts the parcel: “Delete waybill” in the order card or in “Shipments”. After handover — only a return to the sender (editing and deleting).

    Can I extend parcel storage from Elbuz?

    No, storage is extended in the Nova Poshta account. Elbuz shows until what day the parcel waits at the branch and lets you text the customer (manual SMS).

    Why doesn't the “status changed” SMS arrive when Nova Poshta changes the status?

    The condition says “does not equal Initial value”, and it's checked only when a person saves the order. For a status from Nova Poshta, set the condition “Delivery status equals …” (automatic SMS).

    Where it is and who has access

    Menu
    Account → System settings → “Other settings” → “External services and integrations” → Delivery
    Other entry points
    Directories → Documents → Shipments → “Delivery services”; order card → “Delivery” section
    Access right
    connection — “API & access tokens”; parcels — the “Shipments” window; waybills — the “Delivery waybill creation” window
    Prepare
    an API key from the Nova Poshta business account, the city and branch you ship from

    Parcel actions work only for orders the user can see under the “Data scope” setting. The list of account registries is visible only to users with access to all orders: a Nova Poshta registry holds the waybills of every manager.

    1. Create an API keyNova Poshta business account
    2. Enter the key, choose the sender, city and branchExternal services and integrations → Nova Poshta
    3. Check the statuses and open the code windowsSame place, “Notification settings”
    4. Create a waybillOrder card, “Delivery” section
    5. Build a registry, print labels, call a courierShipments
    6. Redirect, return, change detailsShipments, bar above the row

    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