Kiero OMS knowledge base.

Nova Poshta connects to Kiero OMS with your own API key. The current integration covers domestic branch-to-branch delivery in Ukraine and can supply branch selection to Kiero Store.

Before you start

Prepare a Nova Poshta business account with the correct sender and contact details. In OMS you need permission to change settings. A demo organization cannot connect a carrier account. For Store, prepare the Ukrainian market profile and catalogue prices in UAH.

Where to get the API key

Open the Nova Poshta business dashboard and sign in to the account you will use for shipping.
Open Налаштування → Безпека (Settings → Security).
Choose Створити ключ and follow Отримати API Key. Key generation is free, according to the official integration instructions.
Copy the key into the OMS connection form. Do not share it in email, chat or screenshots.

This is the Ukrainian Nova Poshta API connection, not an international Nova Post API account. Carrier charges and account conditions are separate from key generation.

Connect in Kiero OMS

Open Settings → Integrations, add Nova Poshta, and give the connection a recognizable name.
Paste the API key and load the list of senders. Select the sender belonging to this account.
Find and select the dispatch city, then load and select its dispatch branch by number or address.
Load the sender's contacts, select a contact and check the phone number.
Select the delivery payer, payment method and label format: PDF A6 or PDF A4.
Save the connection. The server checks the sender, contact and branch relationships. When editing, leave the key field empty to keep the saved key.

Changing the city resets the branch. Lockers, closed branches and points that only accept incoming parcels cannot be selected for dispatch.

Use the account in Kiero Store

Open Shipping (/admin/shipping) in your Store administration and choose the Nova Poshta account from OMS. Check the saved sender; optionally choose a different sender for this Store. Confirm the binding, set the customer delivery price in UAH and publish the delivery method. Existing saved bindings are restored when you reopen setup.

The API key stays in OMS. A Store-specific sender does not change the shared carrier account. The delivery price published in Store is your configured customer tariff; it is not automatically replaced by the carrier's quote.

Check the connection

Confirm that sender, contact, city and branch lists load. In Store, check that checkout offers the selected city and branch and shows the configured delivery price. These checks do not require creating an order or a waybill.

OMS also has a shipment form for recipient details, weight in kg, dimensions in cm and a whole-number declared value in UAH. PLN amounts are not automatically converted. A quote is required before creation. Cash on delivery is configured separately from the delivery payer and requires an already configured NovaPay payout method.

Verification status, 19 October 2026: directory reads and read-only carrier quotes have been checked. Live waybill creation, labels, tracking, cancellation and cash on delivery still require carrier acceptance. A working directory does not confirm these operations. Address delivery, lockers, international shipments, multiple parcels and return labels are outside the current UI scope.

Troubleshooting and key security

No senders or contacts: check the selected account and its data in the carrier dashboard. Use the contact belonging to the selected sender.
Branch is missing: check the city, branch number and whether it accepts outgoing parcels.
Temporary API limit: wait before loading again. A rate-limit response does not mean the saved key was lost.
Uncertain waybill result: check the carrier dashboard and contact support before retrying; creating another shipment can cause a duplicate.
Key was exposed: replace it in the carrier dashboard and update the OMS connection. Never include it in a support screenshot.