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.

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.7.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.