How Gatemi Distance Shipping Works

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:

  1. 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.
  2. It is kept for Remember a distance for days (30 by default).
  3. Within one request, a repeated question is answered from memory, so a recalculation storm is one call, not fifty.
  4. A failure is never stored. An expired key is temporary; storing "no" for a month would keep refusing long after the problem was fixed.
  5. 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

  1. The journey's distance is converted to your unit; the duration to minutes.
  2. 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 - 5 and 5 - 15 meet cleanly at 5.
  3. The first covering band wins.
  4. Its cost is the flat amount plus the per-unit amount times the whole distance (in the full edition, times the minutes for a time band).
  5. The result is rounded to your store's decimals and never below zero.
  6. 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.00 matches 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 delivery after 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 the free amount 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 the min and capped at the max. Example: 0 - * : 4.00 ; item 0.50 ; max 6 for 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.

Shopping Cart
Scroll to Top