WooCommerce Distance Rate Shipping allows you to set up rules and charge rates based on the distance from your shipping location to the customer’s location.
Rules can be set up to charge shipping based on the distance and total travel time, or the number items in the cart, weight of the items, or the total value of the cart.
This extension requires a Google account as it makes use of Google Maps, the Google Distance Matrix API, and Google Maps Embed API. Some of these features are paid services. The route returned (and subsequent total distance) is used to calculate the cost according to the data returned by Distance Matrix API’s “Driving” Mode.
Installation ↑ Back to top
- Download the .zip file from your WooCommerce account.
- Go to: WordPress Admin > Plugins > Add New and Upload Plugin with the file you downloaded with Choose File.
- Install Now and Activate the extension.
More information at: Install and Activate Plugins/Extensions.
Setup and Configuration ↑ Back to top
The first step in setting up the WooCommerce Distance Rate Shipping extension is to generate an API key on Google, as the extension makes use of the Google Maps and Google Distance Matrix APIs.
Obtain a Google API Key ↑ Back to top
- Go to: https://console.developers.google.com project and sign in with your Google account.
- On the Dashboard screen, click the Library link from the left-hand menu. Then search for and click Google Maps Distance Matrix API.
- Click on the Enable button.
- Then Create to create a new project
- Give your new project a name, i.e., Distance Rate Shipping, and then click Create.
- Click the Enable API button, then click the Credentials tab from either the left-hand menu or the banner across the top.
- Click Add credentials and choose API key.
- A window will pop up, with your new API key. Make sure the restrictions are set to
Don't restrict key.
- Copy the API key generated in the pop-up box and keep it as you will need to enter this in the WooCommerce Distance Rate Shipping extension settings.
- After you copy your API key, close the box and click Overview in the left column. Once again, expand the list of the Google Maps APIs by clicking More and then click Google Maps Embed API.
- Click the Enable API button.
API & Debug
Go to: WooCommerce > Settings > Shipping > Distance Rate.
- API Key – You Google API Key as obtained per instructions above in the Obtaining Google API Key section
- Debug Mode – Enable this to view the API calls on the Cart/Checkout page to debug distance issues.
Store setup ↑ Back to top
1/ Go to: WooCommerce > Settings > Shipping.
2/ Select edit on the Shipping Zone that you want to add the method to
3/ Press the Add shipping method button on the bottom of the Shipping methods section
4/ Select Distance Rate from the dropdown and press Add shipping method:
5/ Click on the new Distance Rate method to configure the settings:
- Method Title – Name the shipping method. This is visible to customers.
- Tax Status – Whether the rates includes tax or not.
- Transportation Mode – Method of transportation that is being used for delivering your products.
- Avoid – Things to avoid when working out the distance; None, Tolls, Highways, or Ferries.
- Distance Unit – Whether to use the Metric or Imperial system for working out distances.
- Show Distance – Whether to show the actual distance on the cart/checkout pages when presenting the customer with their shipping rate.
- Show Duration – Whether to show an approximation of how long the delivery would take.
- Shipping Address – The address from where you are shipping from, this can be your store location or, if you ship from a different location to your store, enter the address of that location here.
Distance Rate Rules
6/ Add Distance Rate Rules to define different settings for shipping.
Multiple rules can be set up with different options:
- Condition is to specify what rules are based on, be it distance, total travel time, cart item count, weight, or cart total value.
- Min and Max to specify a range the type will fall in (travel time based in Minutes). Leave the fields blank if there is no limit.
- Fixed Cost to apply if the rule matches, excluding tax.
- Cost Per Distance / Minute is the value to charge based on the total travel time or distance to the customer address, excluding tax.
- Handling Fee allows you to enter a fixed amount or percentage that is added to the shipping cost (such as 2.50 or 5%).
- Break will stop looking for any other rates below this rule (top-down), if the condition is met. Rates calculated up to the Break point will be offered.
- Abort will disable this shipping method, if the condition is met. No rates will be offered.
Note: Currently, Conditions can only be evaluated individually, not in combination with each other. For example, you can setup distance rules based on order total OR distance, but not order total AND distance.
For a workaround, see the custom snippet at the end of this documentation.
If you selected Total Travel Time, the travel time returned is an average time for the route.
Note: ranges cannot overlap.
A working example is:
- Range 1: 1-9.9 miles
- Range 2: 10-24.9 miles
A nonworking example is:
- Range 1: 1-10 miles
- Range 2: 10-25 miles
7/ Save changes.
Use Cases ↑ Back to top
Only offer Distance Rate Shipping for shipments below a certain distance ↑ Back to top
Let’s say you offer a delivery service within a 50 mile range of your warehouse and want to have the Distance Rate API calculate a delivery cost based on distance traveled, you can set a Distance condition rule with a Max value of 50.
Any distance calculated at Checkout beyond 50 will not match the rule and an error message will be shown:
No cost for the first range, only charge for distances beyond that ↑ Back to top
If you want to allow free shipping for closer deliveries (like the first 20 miles, for example) but charge for shipments further away than that, you can achieve this by adding a “0” cost rule for the free shipping distance (Min 0, Max 20) and then add another rule for distances beyond that (20.1 miles as the Min, Max can be left blank or assigned a range). In this second rule, set the “Cost Per Distance / Minute” amount that you want to charge (for $5 per mile, just enter 5 in that field), but add a negative amount in the “Fixed Cost” field that equals the number of miles in the free distance range multiplied by the cost per mile (20 * 5 = 100, so enter -100 as the fixed cost).
Troubleshooting ↑ Back to top
Error showing on Distance Rate Shipping settings page: ‘Google Maps Platform rejected your request. This API project is not authorized to use this API’ ↑ Back to top
This can happen when Google Maps Embed API is not enabled for the project you created. Open the Google Developer Console and make sure that both Google Distance Matrix API and Google Maps Embed API are added to the project. Select the Enable APIs & Services button and search for each of the above APIs to enable them.
Conditions can only be evaluated individually, not in combination with each other workaround ↑ Back to top
The functionality can be modified with the custom code snippet below. This uses an example of “Override rule cost for distance shipping when destination within 5miles of shop AND order total over $100”
Questions & Support
Something missing from this documentation? Do you still have questions and need assistance?
- Have a question before you buy this extension? Please fill out this pre-sales form – please include the name of this extension in your query.
- Already purchased and need some assistance? Get in touch with a Happiness Engineer via the WooCommerce.com Support page and choose this extension name from the “I need help with” dropdown