1. Documentation /
  2. WooCommerce Distance Rate Shipping

WooCommerce Distance Rate Shipping

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.


↑ Back to top
  1. Download the .zip file from your WooCommerce account.
  2. Go to: WordPress Admin > Plugins > Add New and Upload Plugin with the file you downloaded with Choose File.
  3. 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
  1. Go to: https://console.developers.google.com project and sign in with your Google account.
  2. On the Dashboard screen, click the Library link from the left-hand menu. Then search for and click Google Maps Distance Matrix API
  3. Click on the Enable button.
    • Create to create a new project if needed
    • Give your new project a name, i.e., Distance Rate Shipping, and then click Create.
  4. Click the Enable API button, then click the Credentials tab from either the left-hand menu or the banner across the top
  5. Click Create credentials and choose API key.
    1. A window will pop up, with your new API key, select Restrict Key.
    2. Make sure the restrictions are set to None and Don't restrict key and select Save
  6. Copy the API key generated and keep it as you will need to enter this in the WooCommerce Distance Rate Shipping extension settings.
  7. After you copy your API key, select APIs in the left column.
    1. Select the Maps Embed API under Additional APIs
  8. Click the Enable API button

API & Debug 

Go to: WooCommerce > Settings > Shipping > Distance Rate.

  1. API Key – You Google API Key as obtained per instructions above in the Obtaining Google API Key section
  2. Debug Mode – Enable this to view the API calls on the Cart/Checkout page to debug distance issues.

Enable Billing on Google Cloud Platform

↑ Back to top

As this extension makes use of Google Cloud service (Google Maps and Google Distance Matrix APIs), to ensure the extension work properly, you need to enable billing for your Google Cloud Project on the Google Cloud Platform:

  1. Navigate to the project page on your Google Cloud Platform
  2. Select the project you created during your initial setup for this extension
  3. Click Create Billing Account and complete the rest of the process

Store setup

↑ Back to top
This shipping method has to be added to a Shipping zone. If you haven’t configured your Shipping zones yet, please check our Setting up Shipping Zones guide before proceeding.
  1. Go to WooCommerce > Settings > Shipping > Shipping zones.

2. Click the Edit button on the shipping zone where you want to offer this method.

3. Inside the shipping zone, click the Add shipping method button.

4. Then, select the shipping method and click the Continue button.

  • Click the Edit button on the right side of the Shipping methods table 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.
      You can also use a Google Plus Code for the first line of the address.

Distance Rate Rules

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.
  • Base Cost for rule, excluding tax. Other calculations will be added on top of this cost.
  • Cost Per Distance / Minute is the value to charge based on the total travel time or distance to the customer address, excluding tax.
  • Unit that is used for calculation, either distance or travel time.
  • Multiply by Qty, the cost will be multiplied by quantity.
  • 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

Click 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.

Distance Rate Shipping Max Distance Rule

Any distance calculated at Checkout beyond 50 will not match the rule and an error message will be shown:

Distance Rate Shipping Beyond Shipping Radius

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).


↑ 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”

View on Github

Questions and Support

↑ Back to top

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