CatCode Shipping with Ukrposhta – Post Office Picker & Delivery Rates for WooCommerce

By CatCode

0+ active installationsVersion 1.2.7

Ukrposhta (Укрпошта) shipping for WooCommerce: region, city and post office picker at checkout, live delivery rates through the Ukrposhta eCom API.

Description

Ukrposhta shipping for WooCommerce stores in Ukraine. The customer picks a region, a city and a Ukrposhta post office right in the checkout, and the delivery price in the order total comes from the Ukrposhta eCom API instead of a flat guess.

Ukrposhta (Укрпошта) is the national postal operator of Ukraine with post offices in almost every town and village. Its tariff depends on the recipient’s post index, so the shop needs the exact office, not a free-text address.

What it does

  • Post office picker at checkout: region → city → post office, from the official Ukrposhta Address Classifier. The post index is saved on the order.
  • City search also accepts Latin spelling: “Drohobych” finds Дрогобич.
  • Live delivery rate from the Ukrposhta eCom API, Ukrposhta Standard or Ukrposhta Express. A fallback rate is used when the API does not answer.
  • Free shipping above an order total you set.
  • Optional declared value (insured parcel) and the cash-on-delivery commission, added only for the payment methods you mark as cash on delivery.
  • International rates: for a destination outside Ukraine the rate is quoted by country and weight, with transport type, package type and currency settings.
  • The chosen office is shown on the order screen, on the thank-you page, in the customer account and in order e-mails.
  • Works with the classic checkout and the block checkout. Compatible with HPOS.
  • The eCom Bearer key is stored encrypted. Sandbox mode (dev.ukrposhta.ua) for tests.

Need shipments and labels?

The Pro version of Ukrposhta for WooCommerce on catcode.com.ua adds shipments (barcodes) from the order in one click with cash on delivery, labels 100×100, A4 and A5 as PDF, bulk actions in the order list, the form 103a registry for handing over a batch, and delivery statuses with “Completed” after the parcel is delivered. This free plugin works on its own and has no time limit.

Ukrposhta is a third-party service. This plugin is an independent integration built by CatCode; it is not affiliated with, endorsed by or sponsored by Ukrposhta.

Укрпошта для WooCommerce — опис українською

Доставка Укрпоштою для інтернет-магазину на WooCommerce. Покупець обирає область, місто і відділення Укрпошти прямо на сторінці оформлення замовлення, а вартість доставки рахується за тарифом Укрпошти через eCom API.

  • Вибір відділення Укрпошти: область → місто → відділення з офіційного Адресного класифікатора, поштовий індекс зберігається в замовленні.
  • Пошук міста розуміє і латиницю: «Drohobych» знайде Дрогобич.
  • Живий тариф Укрпошти (Стандарт або Експрес), запасна ставка, якщо API не відповів.
  • Безкоштовна доставка від суми замовлення.
  • Оголошена цінність і комісія за післяплату лише для обраних способів оплати.
  • Міжнародна доставка: тариф за країною і вагою.
  • Обране відділення видно в замовленні, на сторінці подяки, в кабінеті покупця і в листах.
  • Працює з класичним і блоковим оформленням замовлення, сумісний з HPOS.

Потрібен договір eCom з Укрпоштою: Bearer-ключ видає ваш менеджер Укрпошти. Відправлення (ШКІ), ярлики, реєстр 103а і статуси доставки є в Pro-версії на catcode.com.ua.

Укрпошта — сторонній сервіс. Цей плагін є незалежною інтеграцією і не афілійований з Укрпоштою.

External services

This plugin connects to the official Ukrposhta eCom API so the store can show real post offices and real delivery prices at checkout. Nothing is sent anywhere else.

Ukrposhta eCom API and Address Classifier (https://www.ukrposhta.ua, or https://dev.ukrposhta.ua when the Sandbox option is enabled).

  • When: while a customer is choosing a post office at checkout, and whenever the delivery price for a cart has to be quoted.
  • What is sent for the address lookup: the region, the city name being typed and the chosen city id. No customer name, e-mail, phone or order data.
  • What is sent for the price quote: the sender post index from the settings, the chosen post office index, the total weight and dimensions of the cart, and – only when you enable them – the order total as the declared value and the cash-on-delivery amount.
  • Authentication: the eCom Bearer key you enter in the plugin settings.
  • Terms of service: https://www.ukrposhta.ua/ua/informatsiia-pro-poslugu
  • Privacy policy: https://www.ukrposhta.ua/ua/polityka-konfidentsiinosti

Using this plugin therefore means the store agrees to Ukrposhta’s terms; the key is issued by Ukrposhta after an eCom contract is signed.

Installation

  1. Install and activate the plugin (WooCommerce must be active).
  2. Go to WooCommerce → Settings → Shipping and add the “Ukrposhta” method to a shipping zone.
  3. Enter your eCom Bearer key and the sender post index. Save.
  4. Enable the method. The post office picker appears on the checkout as soon as the customer chooses Ukrposhta.

FAQ

Where do I get the Ukrposhta API key?

The eCom Bearer key is issued by your Ukrposhta manager after you sign the eCom contract. Enter it under WooCommerce → Settings → Shipping → Ukrposhta.

Do I need a contract with Ukrposhta?

Yes. Both the Address Classifier (post offices) and the tariff need the Bearer key, and Ukrposhta issues it only under an eCom contract.

Does it work with the block checkout?

Yes. The post office picker works on the classic checkout and on the Checkout block, and an order with the Ukrposhta rate cannot be placed without a post office on either.

How is the delivery price calculated?

From the sender post index, the recipient’s post office index, the cart weight and dimensions, and the service type (Standard or Express). If the API does not answer, the fallback rate from the settings is used. You can also set free shipping above an order total.

Is cash on delivery supported?

The free plugin adds the Ukrposhta cash-on-delivery commission to the rate for the payment methods you list (the standard WooCommerce one is cod). Shipments with cash on delivery are created in the Pro version.

Can it create shipments (ТТН, barcodes) and print labels?

Not in this free plugin. Shipments from the order, PDF labels, the 103a registry and delivery statuses are in the Pro version on catcode.com.ua.

Where does the shop manager see the chosen post office?

In the “Ukrposhta” box on the order screen (city, post office, post index), and in the order totals on the thank-you page, in the customer account and in e-mails.

Screenshots

Changelog

1.2.7

  • Fixed: while the full version from catcode.com.ua is installed, deleting this copy keeps the shared settings and the post office table. Without the full version, deleting still removes everything.
  • Changed: while the full version is active, this copy switches itself off instead of loading next to it (no more PHP warnings).

1.2.6

  • Fixed: uninstalling also removes the settings (including the API tokens) and the city search cache.

1.2.3 – 1.2.5

  • Fixed: the post office no longer becomes the shopper’s account address (also for a guest who registers at checkout); the order still gets the office.
  • Fixed: an office picked earlier no longer leaks into an order shipped by another method; switching away from Ukrposhta restores the shopper’s own address.

1.2.2

  • The post office picker works on the block-based Checkout; a block checkout order cannot be placed with the Ukrposhta rate and no post office.

1.2.1

  • Security: stored API keys are encrypted with AES-256 (OpenSSL). Keys saved by earlier versions keep working.

1.2.0

  • International shipments: the rate outside Ukraine by country and weight; transport type, package type, content category and currency settings.

1.1.0 – 1.1.1

  • Live tariff fixed (every quote used to fall back to the flat rate); re-rate on office or payment change; COD commission only for COD methods.
  • Order screen box, the office on the thank-you page, in the account and in e-mails; Latin city search; optional declared value.
  • English source strings with a bundled Ukrainian translation.

1.0.0 – 1.0.1

  • Initial release: checkout post office picker and live tariff. Works without mbstring; WordPress 5.6 / WooCommerce 6.0 / PHP 7.4.