Skip to content

Delivery and waybills ​

A delivery method is built exactly like a payment method: a key, currencies, properties and an optional driver. With no driver the price comes from a table; with one, the carrier is asked.

Which of the two it is gets decided in one place, DeliveryService::quote(). If that fork lived separately on the cart page and at checkout, the buyer would be shown one price and charged another.

Pricing from a table ​

Enough for pickup and a city courier, and it needs no API, no key and no contract.

FieldWhat it does
pricesthe price per currency
tiersweight bands: upto in grams plus prices. A band with no upto is "and above"
free_fromfree once the goods total reaches this, per currency
max_weightthe weight ceiling in grams; empty means no limit

The order of resolution is: free-above-threshold wins first, then a matching weight band, then the flat price.

Over the weight limit, the method disappears

It is not shown with a refusal — it is removed from the list. A method that cannot carry the parcel is not a choice the buyer should have to understand, and a 21 kg parcel against a 20 kg limit simply has one fewer option.

Pricing from the carrier ​

A driver gets asked instead. Three things are worth knowing about what that costs you.

Answers are cached: a quote for 10 minutes, a city or branch directory for 24 hours, and a failure for one minute — so an API that is down does not get hammered once per page view.

A silent API falls back to the table. If the carrier could not be reached, the method keeps working at the table price, and the fallback is written to the MODX log. That line matters: an unfilled carrier key used to be lost silently, and the shop looked like it was pricing by API when it was pricing by table.

An explicit refusal is different from a failure. When the carrier answers and says it will not carry this, the method is removed from the list — no fallback. Falling back there would quote a price for a service that was just declined.

The carrier's refusal is not shown to the buyer

It never was, and it still is not: the list is built from what is available. The log is where you look when a method you expected is missing.

Pickup points ​

POST /pay/delivery                      methods for the current cart contents
POST /pay/delivery/{key}/cities         city lookup
POST /pay/delivery/{key}/points         branches in a city

The built-in storefront asks for a city by search and then offers two choices. The branch block and the street-address block are never shown together — the one that is off is off entirely, rather than greyed out.

What lands in the order snapshot alongside the street: city_ref, point and point_ref. For Nova Poshta those are the carrier's Ref values; for Ukrposhta the point reference is the postal index, which is what both its pricing and its waybill identify a branch by.

Required address fields ​

Each carrier says which address fields it needs, and the answer depends on where the parcel is going:

DriverTo a branchTo the door
novaposhtanothingcity, street
ukrposhtanothingpostcode, street, building

The server enforces this, not just the form

Until 2026-10-13 the list was announced, travelled to the storefront to put asterisks on the labels, and was checked by nobody on the server. It broke both ways: delivery to a branch demanded an address it has no use for, and Russian Post accepted any address with no postal index.

If you write your own cart template, your form must collect these — the server will refuse with pbs_err_address_fields and name the missing fields.

A method without a driver answers from its own "needs an address" column instead. A method with a driver is never asked that column at all.

Waybills ​

Both drivers in the box issue them. There are three buttons in the order window — issue, track, delete — and the guard against issuing a second waybill sits in the service, not in the drivers: carriers charge per waybill, and getting that wrong costs real money in a way a test will not catch.

Everything a carrier needs goes in the delivery method's properties:

Nova Poshta — api_key, city_sender, sender, sender_address, sender_contact, sender_phone, payer, payment_method, cargo_type, service_type, cod, cod_payer.

The four sender* values are Ref identifiers from the carrier's own directory, not names you type. The recipient, by contrast, is created on the fly. service_type is where the parcel goes: WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors.

Ukrposhta — api_key, token, api_key_tracking, sender_uuid, postcode_sender, type, delivery_type, package, cod, paid_by_recipient, name_order.

Ukrposhta needs three separate credentials

This surprises everyone once. A bearer token for the eCom API, a counterparty token that travels as a query parameter, and a third bearer for status-tracking, which is a different service on a different host. Issuing one waybill takes three API calls: address, then client, then shipment.

Also: for courier delivery it wants the index, the street and the building. It will not accept a waybill with only an index.

Printing the label is not ours. Every carrier's label is its own form, handed over as a finished PDF — Ukrposhta at /shipments/{uuid}/sticker. That is downloading somebody else's file, not rendering ours. Not to be confused with the documents the shop draws itself.

Tracking ​

WaybillService::dueForTracking() selects the parcels worth asking about, and the site's cron calls track() on each — see Subscriptions and cron. A parcel that has arrived and settled stops being selected, instead of being polled forever.

A tracking answer carries a code, a human-readable text, a date, and three separate flags: delivered, returned and paid. Those last two being separate from the first is the whole point:

CarrierCodeMeans
Nova Poshta9handed over — not money
Nova Poshta10handed over, cash collected
Nova Poshta11handed over, money paid out to the shop
Nova Poshta102, 103, 106refused, returned, exchanged
Ukrposhta41000handed to the recipient
Ukrposhta41010handed back to the sender — a return
Ukrposhta31200, 35500return, international return

Ukrposhta has no code of its own for a return

It arrives as the same code as a delivery, 41000, distinguished only by a reason field. The driver composes 41010 to tell them apart. If you are reading codes in your own listener, read the flags instead.

Events and the history feed only fire on a change of code. The cron asks the carrier hourly, and an event per answer would mean a "your parcel is moving" email every hour for as long as it moves.

Cash on delivery ​

This works, end to end: the amount goes out on the waybill, and when the carrier reports the money was transferred, the order becomes paid.

Turn it on with the cod property of the delivery method. The amount then travels in the waybill — BackwardDeliveryData for Nova Poshta, postPayData for Ukrposhta.

How the money gets noticed differs, and neither way is "the parcel arrived":

  • Nova Poshta says so in the tracking status itself — code 11;
  • Ukrposhta does not mention it in tracking at all. It takes a second request to a different endpoint, and the driver only makes that request for a delivered parcel on a method configured for cash on delivery.

Then the shop writes the money down the ordinary way: a payment row is marked paid, and pbShopPaymentSuccess → the order is paid follows from there. There is deliberately no second road to "paid", because the history feed, the stock, the promo code, the receipt and the email all hang off the first one.

The payment recorded is the order total, not the sum transferred

The carrier keeps a commission, so less than the order total reaches the shop's account. But the buyer paid the full price at the branch and the order is paid in full; what was withheld is the shop's expense against the carrier, not the buyer's underpayment. Record the transfer instead and every cash-on-delivery order would read as underpaid, carrying a permanent debt the size of the commission.

The money question is asked before the "has the code changed" gate, and that is not an accident. With Ukrposhta the transfer arrives without the parcel's code changing: an order can sit on "delivered" for a week and then the money lands. Behind that gate the shop would never find out.

Repeats are not a risk: recording is idempotent on the order's payments, not on its status. "The shop has the money" is a state, not an event — the carrier will answer 11 until the end of time.

is_paid on a status is not about money

Worth knowing if you build your own logic on top. In the shipped seed is_paid is set on "Shipped" as well as "Paid" — it means "grant access", not "money arrived". The question "did the money actually arrive" is answered by isSettled(), which looks at the payment rows.

Getting this wrong switched cash on delivery off entirely on a default install: a manager moving an order to "Shipped" — doing exactly what is expected of them — made the shop believe it was already paid.

Events ​

pbShopWaybillCreate    pbShopWaybillStatus
pbShopOrderDelivered   pbShopOrderReturned

A returned parcel does not change the order status by itself. What a return means — a refund, a reshipment, a conversation — is the shop's policy, not the component's.

Next ​

pbShop — a shop component for PageBlocks