Three rules shape this plugin. Each one is a real cost if it is got wrong.
Rule 1: no distance means no rate
Where the distance cannot be worked out, Distance rate offers no rate at all. Not a distance of zero, which would quote local delivery to the other end of the country at the cheapest band, and not "the first band", which is the same mistake. All of these mean the same thing:
- Google cannot be reached, or answers with an error;
- the key is missing, wrong or out of quota;
- there is no road between the two addresses;
- the address is not yet complete;
- no band covers the distance;
- the band is a refusal band.
In each case WooCommerce shows whatever other methods the zone offers, and, if you wrote one, your no rate sentence. A guessed distance is a van sent a long way for very little money, and the merchant only finds out when it comes back.
Rule 2: never ask about an address that is not one
WooCommerce often recalculates shipping for an address that is only a country — before the shopper has typed anything else. Google would happily answer with the distance to the middle of that country. So nothing is looked up until the destination has a country and at least one of a postcode, a street or a city. Until then, Distance rate offers nothing.
The address sent is built from the shipping address lines, city, state name, postcode and country name.
Rule 3: a distance is looked up once and remembered
Google bills each lookup. One checkout recalculates shipping on the cart page, on every address change, every coupon and every quantity change — and the Checkout block asks again through the Store API. So:
- Each journey is stored as a WordPress transient keyed on the origin and destination alone, lower-cased with spaces tidied, plus the travel mode. The cart is not part of the key, because what is in the cart has nothing to do with how far away somebody lives.
- It is kept for Remember a distance for days (30 by default).
- Within one request, a repeated question is answered from memory, so a recalculation storm is one call, not fifty.
- A failure is never stored. An expired key is temporary; storing "no" for a month would keep refusing long after the problem was fixed.
- Saving the settings clears WooCommerce's cached shipping rates, so new settings apply on the next recalculation.
Journeys are stored in metres and seconds, never in your unit, so switching between kilometres and miles can never misread a stored distance.
The lookup
The plugin calls Google's Routes API (computeRouteMatrix) — the current API Google recommends, not the legacy Distance Matrix API — with a POST from your server. The key travels in a request header, not the URL, so it does not end up in proxy logs. The request times out after 5 seconds. Only a route Google says exists counts.
Pricing a band
- The journey's distance is converted to your unit; the duration to minutes.
- Bands are read in the order you wrote them. A band covers a journey when the journey is at least its from and below its to — the upper end is exclusive, so
0 - 5and5 - 15meet cleanly at 5. - The first covering band wins.
- Its cost is the flat amount plus the per-unit amount times the whole distance (in the full edition, times the minutes for a
timeband). - The result is rounded to your store's decimals and never below zero.
- The rate is added as one line, with tax calculated per order rather than split per item.
Worked example, in kilometres: bands 0 - 5 : 3.00 and 5 - 15 : 5.00 + 0.40. A delivery 8.5 km away matches the second band and costs 5.00 + 0.40 × 8.5 = 8.40. One exactly 5 km away also matches the second band (5.00 + 2.00 = 7.00), because the first band stops below 5.
Full edition
- Time bands.
time 0 - 20 : 4.00matches journeys under 20 minutes' drive. Distance and time bands can be mixed; the first covering band still wins. - Refusal bands.
40 - * : x We only deliver within 40 km.offers no rate and shows that sentence, so a shopper knows why. - Band labels.
| City deliveryafter the cost renames the rate for that band. - Extras, typed after semicolons.
0 - * : 4.00 ; item 0.50 ; 2% ; min 5 ; max 20 ; free 80. A band is priced in this order: if the goods are worth at least thefreeamount the delivery costs nothing; otherwise the flat amount, the per-unit amount times the journey, the per-item amount times the items in the cart and the percentage of the goods are added together, then raised to theminand capped at themax. Example:0 - * : 4.00 ; item 0.50 ; max 6for a basket of six items is 4.00 + 3.00 = 7.00, capped at 6.00. - Travel modes. Motorbike, bicycle and on-foot routes, for couriers who are not in a van.
- Logging. Failed lookups, with Google's own reason, in WooCommerce → Status → Logs.
Free edition and the full edition's bands
The free edition reads the same bands. A time band it cannot measure means no rate from that point down — silence rather than a charge it cannot justify — and a refusal band still refuses. Bands that would be priced in the full edition are therefore never priced more cheaply here.
