Ukrposhta — Ukrposhta shipping for OpenCart 2.3, 3.x & 4.x

Ukrposhta Shipping for OpenCart 4 is a Ukrposhta shipping module: a branch-picker widget (region → city → branch) at checkout, based on the official Address Classifier, and live domestic shipping-cost calculation via the eCom API. The branch the customer picked is recorded on the order, so a manager doesn’t have to ask for the address again over messenger.

The module is free. It installs as a standard OpenCart extension (ocmod) and needs no theme edits — the widget hooks in via the event system.

How it works, step by step

1. The admin installs the extension, clicks “Install” on the settings page — the module creates its tables, events and cron tasks — and syncs regions with one click.
2. The eCom Bearer token and sender index are entered; “Test connection” and “Test rate” buttons instantly confirm the key is accepted and the API responds.
3. At checkout, the customer chooses Ukrposhta delivery — the footer/after event loads the widget, which walks through region → city → branch.
4. The module requests a rate from the eCom API using the sender’s and recipient’s postal indices; if the API is unavailable, a default rate from the settings is shown instead.
5. After checkout, the order.addOrder/after event saves the chosen branch (index, city, name) along with the order.
6. Once a week, OpenCart’s cron refreshes the region classifier cache — the directory never goes stale.

What it looks like

Pricing

Free. Download ukrposhta-1.2.0.ocmod.zip from the module page and use it with no subscriptions or paid versions.

Technical requirements

• OpenCart 4.0.2 – 4.1.x
• PHP 7.4 and newer
• An eCom agreement with Ukrposhta: the Bearer key is issued in the eCom account after signing the agreement — it’s needed for the address classifier and rate calculation
• For rate calculation — the sender’s warehouse postal index

Under the hood

• The Bearer key is encrypted before being written to the database; the settings form shows only a “saved” mask, never the plain value.
• The classifier is cached in the module’s own tables (up_regions, up_cities, up_offices) — checkout reads the local database rather than hitting the API on every request.
• Integration is via OpenCart events (footer inject, order added) — no OCMOD controller patches or theme template edits.
• Standard OpenCart shipping-method settings: geo-zone, tax class, sort order.
• The widget’s look is configurable: accent colour, corner radius, theme (auto/light/dark).
• There’s a sandbox toggle for working against Ukrposhta’s test environment.

How to install

1. Download the build for your version and install it via “Extensions → Installer”: ukrposhta-1.2.0.ocmod.zip for 4.x, ukrposhta-oc3-1.2.0.ocmod.zip for 3.x, ukrposhta-oc2-1.1.0.ocmod.zip for 2.3.
2. In “Extensions → Extensions → Shipping” find “Ukrposhta shipping” and click Install.
3. Open the settings and click “Install” — the tables, events and cron tasks are created.
4. Enter the eCom Bearer token and sender index, click “Test connection”, then “Sync regions”.
5. Enable the shipping method and save — the branch-picker widget will appear at checkout.

Version history

1.2.0 (4.x, 3.x) · 1.1.0 (2.3) — 20 August 2026

International shipping calculation added. For addresses outside Ukraine, the rate is calculated by destination country and weight, and no branch needs to be chosen: checkout gets an “Other country” toggle that brings back the regular address form. 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 (some countries are closed for a given shipment type), the customer sees the reason rather than a made-up amount from a fallback rate. Verified live: Poland 1 kg — 867 UAH, 5 kg — 1,500 UAH, Canada 3 kg — 1,627 UAH.

1.1.2 (4.x) · 1.1.1 (3.x) · 1.0.1 (2.3) — August 2026

The live Ukrposhta rate is finally calculated. It turned out the /domestic/delivery-price request wasn’t going through at all: 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, the storefront always showed a flat rate from the settings. Verified live on all three platforms: Kyiv → Drohobych, 3 kg — 55 UAH, with declared value — 67.50, cash-on-delivery fee — 65.

3.x 1.1.0 — 11 August 2026

The OpenCart 3 build was brought up to the level of 2.3 and 4.x. The widget now hides only the fields it fills in itself at the shipping step: the recipient’s first and last name stay on screen — previously they were hidden along with the address, and “Continue” hit an error on a hidden field. The region in the native dropdown is now set reliably: OpenCart reloads the region list after a country change, so the selection is repeated for a few seconds until the list settles. If the customer switches to a different carrier, the native address form comes back (previously it stayed hidden forever). The chosen branch is now stamped into the order’s address on the server, and a shipment draft is no longer created for orders using a different shipping method. Without a Ukrposhta key, an offline region list works, with city and a 5-digit index entered manually. A zero rate is labelled “cash on delivery” rather than “0 UAH”. Address protection was moved to OpenCart 3 events — core checkout files aren’t patched.

1.1.0 — 5 August 2026

Fixed a dead PHP 7.4 polyfill: the polyfill file had a WordPress ABSPATH guard copied into it, which never exists in OpenCart — so including the file broke the whole request, functions weren’t declared, and the page died blank. The module now genuinely works on PHP 7.4. The addOrder event is now registered with a single * rule that covers both 4.0.x and 4.1.x (previously two lines were written, duplicating the event on 4.0.2); the old line is removed on install. A duplicate notification container in the admin, which sent “saved” toasts to the wrong place, was removed, and the “first run — click Install” hint no longer lingers on an already-installed module.

1.0.12 — 24 July 2026

The widget scrolls into view as soon as Ukrposhta is chosen — on mobile it renders above the shipping-method selector and was easy to miss.

1.0.11 — 24 July 2026

City search no longer fails silently without the mbstring extension: mb_strlen / mb_strtolower are now guarded, and autocomplete works on any hosting.

1.0.10 — 23 July 2026

Saving contact details no longer resets an already-chosen shipping and payment method.

1.0.8–1.0.9 — 23 July 2026

The order’s address is now filled with exactly what the customer picked (the classifier’s city, the region in Cyrillic, the branch’s real postal index), plus manual index entry.

1.0.4 — 23 July 2026

Fixed a fatal error in shipping-method calculation: getQuote() was loading a catalog model, localisation/geo_zone, that doesn’t exist in OpenCart 4.x, which meant the entire list of shipping methods failed to appear (“Shipping address required”). The geo-zone is now checked with a direct query against zone_to_geo_zone. Also: the region → city → branch block now appears only after the “Ukrposhta” method is chosen (method first, then fields), and comes with a demo set of regions/cities/branches for a clickable test with no eCom Bearer key.

1.0.0 — July 2026

First public release: a region → city → branch widget at checkout, a live domestic rate via the eCom API, key encryption, weekly classifier sync via cron.