Troubleshoot Distance Shipping Issues in Magento 2

• Module Enabled: Magmodules → Shipping Costs Based on Distance → General → Enabled = Yes
• Shipping Method Enabled: Shipping Method → Name and Position → Enabled = Yes
• API Key Set: General → API and Location Details → API Key is filled in
• Store Address Set: General → API and Location Details → Store Address is filled in

• Country: Is the customer's country in the allowed countries list?
• Distance: Is the customer within the maximum distance limit?
• Order Amount: Does the order meet the minimum order amount requirement?

If conditions are enabled:

• Are all cart products eligible for distance-based shipping?
• If using "Show only for eligible products," ensure products meet criteria
• Check the product attribute used for eligibility

1. Click Test Credentials in configuration
2. Run CLI selftest: bin/magento distancebasedshipping:selftest
3. Check if API key is valid and has proper permissions

• Check that distance ranges don't have gaps
• Ensure the customer's distance falls within a defined range
• Review fixed price and per-km rate settings

• Round Distance: Affects the distance used in calculations
• Round Total Price: Affects the final displayed price

• Minimal Price: Is the calculated price being raised to minimum?
• Maximum Price: Is the calculated price being capped?

• Is free shipping enabled?
• Does the order meet the free shipping threshold?

1. Enable Debug Mode in configuration
2. Place a test order
3. Check logs in var/log/ for calculation details

• Verify the key is copied correctly without extra spaces
• Check the key exists in Google Cloud Console
• Ensure the key hasn't been deleted or regenerated

• Enable Distance Matrix API in your Google Cloud project
• Wait a few minutes after enabling
• Verify you're using the correct project

• Check API key restrictions in Google Cloud Console
• Verify billing is set up on the project
• Ensure server IP is whitelisted (if IP restriction is enabled)

• You've exceeded your API quota
• Wait for quota to reset (daily/monthly)
• Consider upgrading your Google Cloud plan

• Google can't find a route between addresses
• Verify store address is valid and findable
• Customer address may be incomplete or invalid

• Store or customer address is malformed
• Check address format in configuration
• Ensure address includes all required components

• Test your store address in Google Maps directly
• Use full address format: street, city, postal code, country
• Avoid PO Box addresses
• Don't use special characters

Configure fallback behavior:

1. Go to Shipping Method → Address Not Found
2. Choose Hide shipping method or Show with message
3. Set a helpful error message for customers

• Check Add Shipping Estimation to Product Page is enabled
• Clear cache after enabling
• Verify the product page template supports the estimation block

• Product page estimation uses entered postcode only
• Full address at checkout may result in different distance
• This is expected behavior

• Distance calculation adds API latency
• Enable caching if available
• Consider using a closer Google Cloud region

• Monitor usage in Google Cloud Console
• Set up billing alerts
• Review if unnecessary API calls are being made

• Check distance limits - some customers may be too far
• Verify country restrictions
• Check if customer's address is findable by Google

• Review the pricing table and calculation method
• Check which distance range applies
• Verify rounding settings
• Look for min/max price caps

• API key may have expired or been deleted
• Billing may have been disabled on Google Cloud
• Configuration may have been changed
• Run selftest to diagnose