Shipping Cost by Distance

What it does

The add-on replaces flat-rate and zone-based shipping with a model that charges customers based on the actual distance between the store (or seller in Multi-Vendor) and the delivery address. Distance is retrieved via Google Maps, Yandex or the free OpenStreetMap Nominatim service and matched against rate tables you configure directly inside each shipping method. The result is a fair, transparent shipping cost that scales with real geography.

⚠ Important — external API costs: Google Maps and Yandex are pay-per-use services billed by the provider directly — the add-on licence does not include API credits. If you want to avoid third-party costs entirely, choose the OpenStreetMap provider: it uses the free public Nominatim geocoder with no API key or usage fees.

Key features

• Three map providers — choose Google Distance Matrix, Yandex Distance Matrix, or free OpenStreetMap (straight-line via Nominatim) from a single selector; switch at any time without losing your rate tables.
• Automatic provider fallback — if Google or Yandex returns an error or timeout, the add-on seamlessly falls back to OpenStreetMap so shipping cost is always calculated.
• Distance-based rate tables — add distance (D) conditions to any existing shipping method alongside price, weight and item-count conditions; fully compatible with CS-Cart 4.13.1+ base-rate structure.
• Min / max billable distance — set a floor and ceiling for the distance used in calculations to handle nearby or very distant orders correctly.
• Built-in session cache — calculated distances and geocoding results are stored in the cart session with a configurable TTL, cutting API calls and protecting your quota.
• Built-in connection test — verify your API key and provider availability directly from the add-on settings page with a one-click connectivity check.
• Detailed logging — three log levels (errors / warnings / debug) with optional masking of sensitive data (addresses, API keys) to stay GDPR-compliant.
• Distance on the product page — optionally show the calculated distance and route addresses to customers on the product detail page to build delivery transparency.
• Multi-Vendor & Ultimate ready — in Multi-Vendor each seller's warehouse address is used automatically; in Ultimate the company settings address is resolved per-store.
• Self-hosted Nominatim support — point the add-on at your own Nominatim server for high-volume stores that need no usage-policy limits.

How it works

1. Install & configure — select a map provider, enter your API key (required for Google and Yandex; not needed for OpenStreetMap), set distance units (km or mile) and save.
2. Set up rate tables — open any shipping method, add distance conditions and specify the rate for each distance bracket, just like you would for weight or price conditions.
3. Customer checks out — the add-on geocodes the customer's shipping address and the seller's address, requests the road distance from the selected provider, and feeds the result into CS-Cart's shipping rate engine.
4. Rate is applied — CS-Cart picks the matching distance bracket and displays the corresponding shipping cost at checkout. The result is cached for the session so subsequent page loads are instant.

Requirements

• CS-Cart or Multi-Vendor 4.9.0 or higher
• Google Maps API key — required when using the Google provider (get a key)
• Yandex Distance Matrix API key — required when using the Yandex provider (get a key)
• No API key needed for OpenStreetMap / Nominatim (public server or self-hosted)

Provider comparison

Google and Yandex provide more accurate results for routes with winding roads or detours. OpenStreetMap is faster and free, but may underestimate actual driving distance in complex terrain.

Common questions

Q: Does it work with Multi-Vendor?
A: Yes. Each vendor's warehouse address is resolved automatically. Distance is calculated per seller, so customers with items from different vendors get separate distance-based rates.

Q: Do I need to pay for a Google Maps or Yandex API key?
A: Yes, if you choose Google or Yandex as the provider. Both services are billed by their respective companies on a pay-per-use basis — the add-on licence does not cover these costs. The built-in session cache minimises the number of API calls, but charges from Google or Yandex will still apply based on your traffic. If you want zero third-party costs, choose the OpenStreetMap provider — it is completely free (public Nominatim server) or can be self-hosted.

Q: What happens if the map provider is temporarily unavailable?
A: Enable "Fallback to OpenStreetMap on provider error". If Google or Yandex fails, the add-on automatically switches to OpenStreetMap so shipping cost is always calculated.

Q: Will it slow down my checkout?
A: No. Results are cached in the cart session (TTL is configurable). The distance API is called only when the address changes; all subsequent requests within the session use the cached value.