Ukrposhta — branch picker + rate for WooCommerce

Ukrposhta Shipping for WooCommerce is a Ukrposhta shipping plugin for WooCommerce stores. The customer picks a branch right in checkout via a region → city → branch chain, and the shipping cost is calculated live through Ukrposhta’s official eCom API. Data comes from the official Address Classifier, so the list of branches is always current, and the chosen postal index is saved on the order.

The plugin is completely free. The code is open — the repository is on GitHub (catcodestudio/woocommerce-ukrposhta-shipping), GPLv2 licence.

What it looks like to the customer

Once “Ukrposhta” is chosen as the shipping method at checkout, a widget appears: the customer picks a region, then a city, then a specific branch. As soon as a branch is picked, the plugin requests a rate from the eCom API (accounting for cart weight and the sender’s and recipient’s postal indices) and shows the real shipping cost. The widget’s accent colour can be adjusted to match your theme.

What the admin gets

The method is added to a WooCommerce shipping zone, and the credentials are global — one Bearer token for the whole store, regardless of how many zones you have. Settings include: a test environment (sandbox dev.ukrposhta.ua), the service type (Standard or Express), a default rate for when the API is unavailable, and a free-shipping threshold based on order total. The branch the customer picked is visible right on the order — a separate “Ukrposhta” block with the city, branch and index, plus a line in emails and on the thank-you page.

How it works, step by step

1. The admin enters the eCom Bearer token and the sender’s postal index, and adds the “Ukrposhta” method to a shipping zone.
2. At checkout, the customer chooses Ukrposhta delivery — a region → city → branch picker appears, based on the official Address Classifier.
3. The plugin calculates the cart weight and requests a rate via the /domestic/delivery-price endpoint; if the API is unavailable, a flat rate from the settings is used instead.
4. If the customer chose cash on delivery, Ukrposhta’s cash-on-delivery fee is added to the rate — and disappears the moment they switch to prepayment.
5. If the order total exceeds the configured threshold, shipping becomes free.
6. The customer places the order — the chosen branch’s postal index is saved on the order and available to the admin for shipping.

Pricing

Free. The plugin is distributed under the GPLv2 licence, with the code open on GitHub. There are no paid versions or subscriptions.

Technical requirements

• WordPress 5.6+ (tested up to 6.7)
• WooCommerce 6.0+ (tested up to 10.7)
• PHP 7.4+
• An eCom agreement with Ukrposhta: your Ukrposhta account manager issues a Bearer key after the agreement is signed — it’s needed both for the address classifier and for rate calculation

Under the hood

• The Bearer key is stored encrypted at rest, and is never shown in plain text back in the settings form.
• The branch directory is cached in a dedicated upwc_offices table, and the list of regions in a transient: checkout doesn’t hit the Ukrposhta API on every load.
• HPOS (custom order tables) compatibility is officially declared; order meta is captured on both the classic checkout and the Store API (block) path.
• The rate accounts for the weight of items in the cart, an optional declared value, and the cash-on-delivery fee — but only for payment methods you’ve marked as cash on delivery.
• The chosen branch is part of the WooCommerce shipping package, so changing the branch or payment method recalculates the rate rather than showing a cached one.
• City search understands Latin script: “Drohobych” finds Дрогобич.
• Translation-ready: the text domain and all strings are ready for localisation.

How to install

1. Download ukrposhta-shipping-for-woocommerce-1.2.0.zip and install it via “Plugins → Add New → Upload Plugin”.
2. Activate the plugin — the branch cache table is created automatically.
3. Go to WooCommerce → Settings → Shipping and add the “Ukrposhta” method to the zone you need.
4. Enter the eCom Bearer token and the sender’s postal index, and save.
5. Enable the method — the branch picker will appear at checkout.

Version history

1.2.0 — 20 August 2026

International shipping calculation added: for addresses outside Ukraine, the rate is calculated by destination country and weight, and no branch is needed. Just add the method to a shipping zone with the countries you need. The settings let you set the transport mode (air or ground), shipment type, contents category and the rate’s currency. If Ukrposhta can’t quote a direction, the method isn’t shown with a made-up price — the reason is written to “WooCommerce → Status → Logs”. Verified live: Poland, 1.5 kg — 945 UAH.

1.1.1 — August 2026

Source strings moved to English, with Ukrainian shipped as a separate translation bundled with the plugin — the module can now be translated into any language, while looking the same in Ukrainian. Checkout widget labels are now translatable too. A build for the wordpress.org directory was prepared.

1.1.0 — August 2026

The live Ukrposhta rate is finally calculated: measurements need to be sent inside parcels, and the sender index as a string (01001 was being turned into 1001, and the API rejected the request). Before this, checkout always showed a flat rate. The cash-on-delivery fee is no longer added to prepaid orders. The chosen branch is visible on the order, in emails and on the thank-you page. Checkout no longer lets an order through without a chosen branch. The declared value became optional. City search understands Latin script. The widget stays hidden until Ukrposhta is chosen, and doesn’t appear on the thank-you page.

1.0.1 — July 2026

Works on hosting without mbstring: city search and the parcel description no longer fail silently. The requirements floor was lowered to WordPress 5.6 / WooCommerce 6.0 / PHP 7.4.

1.0.0 — July 2026

First public release: a branch picker (region → city → branch) at checkout and live rate calculation via the eCom API, with a fallback to a flat rate.