↑↓ selectEnter openEsc close

    1. Elbuz

    How to connect Ukrposhta delivery in your store

    4 min readUpdated

    With Ukrposhta delivery, the customer picks a branch from the list at checkout or a courier to the door. The store suggests places and branches and doesn't let a wrong address through.

    When you need this:

    • Customers from villages and small towns — Ukrposhta has branches where other carriers don't.
    • The customer doesn't know the branch number — they find it by postcode or street.
    • Small items — a fixed delivery price and free delivery above a cart total.
    • The customer wants it at the door — a Ukrposhta courier delivers to the address.

    Where to start: “Store settings” → “Delivery” → turn on Ukrposhta and paste the token.

    What Ukrposhta delivery can do

    How to connect Ukrposhta

    You need a contract with Ukrposhta as a sole proprietor or a company. Ukrposhta issues access tokens with it. The store needs one of them — in the contract annex it's the PRODUCTION BEARER eCom line.

    1. Open the delivery screen. “Store settings” → “Delivery” section → “Delivery” card.
    2. Turn on Ukrposhta in the “Carriers” block. In a new store it's off.
    3. Paste the token into the “Ukraine · Ukrposhta” block, the “Ukrposhta token (Bearer eCom)” field.
    4. Check the prices in the “Prices and options” block (see below).
    5. Click “Save”. The settings go to the store right away.
    The Carriers block of the Delivery module with the Ukrposhta row
    1Carrier switch
    2Drag handle
    3Ukrposhta
    1. The switch shows the Ukrposhta methods at checkout after saving.
    2. Drag the row to change the order of the delivery options at checkout.
    3. The name opens the Ukrposhta settings block.
    The Ukraine · Ukrposhta settings block with the saved token field and the Replace button
    1Token field (saved)
    2Geo zone
    3Replace
    1. The PRODUCTION BEARER eCom token from the Ukrposhta contract; a saved token is never shown.
    2. Who sees Ukrposhta; “All zones” means everyone.
    3. Replace the token, for example after signing a new contract.

    You can't save Ukrposhta turned on without a token: the field shows “Required — the module will not work without it”. On the right, under “Still to set up”, you'll see “Not set: Ukrposhta token (Bearer eCom)”.

    Copy the whole token, with no spaces. After saving, the token isn't shown — only a mark that it's set. To change it, click “Replace” and enter the new one.

    “Geo zone” limits who sees Ukrposhta: only addresses in that zone. “All zones” means everyone. For a zone made of separate regions, the store checks it once the customer picks a city from the list; until then, only the country.

    The order of carriers in the list is the order of options at checkout: drag a row up or down. The screen's common blocks are covered in “Delivery in your store”.

    When branch hints appear

    The store loads the list of cities and branches from Ukrposhta on its own, once a day, using your token. The first load happens within a day of saving the token. To load it right away, contact Elbuz support.

    Before the first load, Ukrposhta is already at checkout, but without hints. The customer types the city and branch, and the store doesn't check them.

    • Only working branches go into the list: the customer won't see closed ones.
    • The list has only cities with such a branch. A courier can be ordered only there too.
    • While the list updates, checkout works with the old one.
    • If the update fails, for example because the token is wrong, yesterday's list stays.

    What the customer sees at checkout

    The customer picks an option and fills in the fields:

    FieldHow it works
    CitySearch by the start of the name. The hint shows the place type, district and region, so villages with the same name aren't mixed up
    BranchSearch by postcode (“79005”) or part of the address. The order gets “Відділення 79005: адреса” (branch 79005 and its address)
    StreetCourier only. Street hints start from two letters
    House, FlatCourier only. The house is required, the flat isn't
    PostcodeCourier only, required: 5 digits. Goes into the order and the waybill

    “Ukrposhta Standard” and “Ukrposhta Express” lead to the same list of branches. Each has its own title, price, free delivery and weight limit.

    What the store checks

    Once the list is loaded, the store won't accept an order with an address that isn't on it. The customer sees a hint under the field:

    MessageWhen
    “Ukrposhta delivers only to places with its post office: pick a place from the list or another delivery method”The place was typed by hand and isn't on the list. Applies to the courier too
    “Pick the branch from the list”The branch was typed by hand
    “Enter the house number”Courier without a house number
    “Enter the postcode: 5 digits, for example 79005”Courier without a postcode, or the postcode isn't 5 digits

    The order country is Ukraine; the region is filled in from the city picked from the list. Ukrposhta doesn't hide cash on delivery.

    Price, free delivery and weight

    The store doesn't calculate the Ukrposhta rate: the customer sees the price you set. You set it in the “Prices and options” block, separately for each option.

    The Ukrposhta group in the Prices and options table
    1Title for the customer
    2Price
    3Free from
    4Up to, kg
    1. The title shown at checkout for each language; empty means the default title.
    2. The delivery price; 0 means the carrier's tariff.
    3. From this cart total delivery is free; 0 means off.
    4. A heavier cart hides the method; 0 means no limit.
    ColumnWhat it doesDefault
    EnabledWhether the option is shown at checkoutall three are on
    Title for the buyerThe title at checkout, separately for each language. Empty means the default one“Ukrposhta Standard”, “Ukrposhta Express”, “Ukrposhta courier”
    PriceDelivery price in the store currency. 0 — the customer sees “Carrier rates”, and delivery isn't included in the order total0
    Free fromFrom this cart total, delivery is “Free”. 0 — off0
    Up to, kgIf the cart is heavier, the option isn't shown. 0 — no limit0

    The store calculates the cart weight from product weights. A product without a weight doesn't affect the “Up to, kg” limit.

    The order in Elbuz and the waybill

    An order from the website arrives in “Customer order” documents with Ukrposhta as the delivery service. A branch picked from the list arrives together with its postcode.

    In the Ukrposhta waybill form, Elbuz fills in the recipient's postcode itself — the branch postcode. “Standard” and “Express” arrive in Elbuz the same way — as the Ukrposhta service.

    A courier order opens the waybill form with “Shipping method” set to “Address” and the postcode the customer entered.

    The waybill form sets the delivery payer itself: delivery in the order is 0 — “Recipient”, otherwise “Sender”. You can change it before creating the waybill.

    Keys for waybills are set separately, in “External services and integrations”. More: Ukrposhta API in Elbuz.

    Scenarios

    Accessories: the cheapest delivery for small items

    “Ukrposhta Standard”: “Price” — 40, “Free from” — 500. A UAH 300 phone case reaches the customer for UAH 40, a UAH 600 set ships free.

    Heavy appliances — courier only

    In “Ukrposhta Standard” and “Ukrposhta Express”, “Up to, kg” is 30. A cart with a fridge is heavier: the branch options are hidden, and “Ukrposhta courier” remains. A kettle the customer still collects at a branch.

    Spare parts: a fast option on its own

    In “Ukrposhta Express”, the title for the buyer is “Express: 1–2 days”, and the price is higher than Standard's. A customer whose washing machine is broken will pick the faster option.

    Seeds and garden supplies

    Turn on all three options. Customers from villages will find their branch by postcode, even if they don't know its number.

    What to do when delivery doesn't work

    What you seeWhyWhat to do
    “Save” doesn't work, with the “Required — …” warning under the token Ukrposhta is on without a token Paste the PRODUCTION BEARER eCom token from the contract or turn Ukrposhta off
    The customer doesn't see Ukrposhta at checkout The carrier, all its options or the main switch in “Advanced” is off, the address is outside the geo zone, or the cart is heavier than “Up to, kg” Check “Carriers”, “Prices and options”, “Geo zone” and “Advanced”. If the options are the problem, the right panel shows “Ukrposhta: all options are off…”
    No city or branch hints The list isn't loaded yet, or the token is wrong Wait a day. Still no hints — check the token and the main switch in “Advanced”, or contact Elbuz support
    The customer can't find their branch The branch isn't working, or they aren't searching by postcode Suggest searching by postcode or street, or picking a nearby branch
    The recipient's postcode is empty in the waybill form The branch was typed by hand before the branch list was loaded Ask the customer for the postcode and enter it in the waybill form

    FAQ

    Can I connect Ukrposhta without a contract?

    No. Without the contract token, you can't save Ukrposhta turned on, and the branch list can't be loaded.

    Why doesn't the store calculate the price by the Ukrposhta rate?

    The store doesn't request the rate from Ukrposhta. Set your own price, free delivery above a cart total, or 0 — “Carrier rates” (Price).

    What happens if I turn Ukrposhta off?

    Its options disappear from checkout. The token, prices and titles are kept: turn it back on and everything is in place.

    Does cash on delivery work with Ukrposhta?

    Yes, the store doesn't hide it. Which payment methods appear at checkout is set in the “Checkout & payment” section.

    Why can't the customer find their village in the list?

    The list has only places with a working Ukrposhta branch. Have them pick the nearest branch in a neighboring place.

    Where to find it and who has access

    Menu
    Directories → Operations → Store settings → “Delivery” → “Delivery”
    Access rights
    the “Store settings” window in group permissions
    Prepare
    a contract with Ukrposhta, the PRODUCTION BEARER eCom token

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free