Setting up Nova Poshta delivery

The Nova Poshta integration lets customers choose a branch, parcel locker or door-to-door delivery right at checkout, while you create express waybills directly from the order card — no manual data entry in the carrier's cabinet.

Step 1. Get an API key in your Nova Poshta cabinet

1. Register a business cabinet at new.novaposhta.ua or sign in to an existing one.
2. Open Settings → Security (Налаштування → Безпека) and click Create key.

   

3. Confirm key creation with the Create button.

   

4. Copy the value from the Key column — you will need it in step 4.

   

Note: the API key is issued for 1 year. Once it expires it stops working — see the end of this article for how to extend it.

Step 2. Enable the Nova Poshta delivery method

In the store admin panel open Shop → Delivery methods. Nova Poshta is already in the default list — make sure its toggle in the On/Off column is enabled.

When editing the method you can set the "Free delivery from, UAH" threshold — once the order total reaches it, delivery becomes free for the customer.

Important: do not delete the Nova Poshta method from the list — the city and branch fields at checkout are tied to it. If you don't need it temporarily, just switch it off with the toggle.

Step 3. Link payment methods

Open Shop → Payment methods and, in every payment method that should be available for Nova Poshta, add it in the Delivery methods field. Without this link a customer who picks Nova Poshta will see no payment options at all.

Step 4. Create an account in the Nova Poshta section

Open Integrations → Nova Poshta. The section has three tabs: Waybills, Dictionaries and Accounts. Until an account exists you will see the "An account must be created" notice.

Go to the Accounts tab, click + Create and fill in the form:

• API key — the key from step 1;
• Name — any account name, e.g. your store name;
• Payer — who pays for delivery by default: Sender, Recipient or Third party;
• Payment method — Cash or Non-cash;
• Cargo type — Parcel, Cargo, Documents, Tires/wheels or Pallets;
• Service type — the default scheme, e.g. Branch-to-Branch.

The first account automatically becomes the primary one — its API key is used for all Nova Poshta requests. You can have several accounts (e.g. different senders); the primary one is marked in the list.

Step 5. Import the dictionaries

Open the Dictionaries tab and click Import dictionaries. You will see "Import started. Please wait..." — the system downloads Regions, Cities and Branches/Parcel lockers from the Nova Poshta API in the background; the tab shows counters of imported records.

Nova Poshta opens new branches regularly, so re-run the import from time to time.

Step 6. Set the sender's city and branch

Return to the Accounts tab and open your account for editing. After the dictionary import, the searchable City and Branch fields become available — set where you will ship parcels from. Adjust the Recipient type and other defaults if needed and click Save.

Step 7. Check the checkout

Open your storefront, add a product to the cart and choose Nova Poshta delivery. The form should show: Type (Branch / Parcel locker / Address), Region, City and Branch or parcel locker. If the city lists are empty — see "Troubleshooting" below.

Creating an express waybill from an order

When a customer places an order with Nova Poshta delivery, open it in Shop → Orders — the order card has a Nova Poshta tab:

• the recipient's city and branch are filled in from the order automatically;
• set the shipment parameters: declared value, shipping date, weight and dimensions, cargo description; enable Payment control or order a Return delivery if needed;
• click Generate waybill — the waybill is created in your Nova Poshta cabinet. You can then print it, regenerate it after changes, or delete it.

All created waybills are listed under Integrations → Nova Poshta → Waybills: number, date, recipient, weight, status, delivery cost and date.

Extending the API key validity

The key is valid for one year. To extend it: in the Nova Poshta cabinet open Settings → Security, click the clock icon ("Extend key validity") next to the key and confirm with the Confirm button.

Only a key that has not yet expired and has not been revoked can be extended. If it has already expired — create a new key and update it in the account (step 4).

Troubleshooting

• Empty city or branch lists at checkout — the dictionary import has not been run (step 5) or the API key is invalid.
• "API key required" / "An account must be created" notices — there is no active primary account with a key (step 4).
• The customer picked Nova Poshta but sees no payment options — payment methods are not linked to the delivery method (step 3).
• The waybill is not created — check the API key validity and that the sender's city and branch are set in the account (step 6).