# Magento 2 Distance Based Shipping
### Installation and User Guide for Magento 2 Distance Based Shipping Extension
**Table of Contents**
1. [*Installation* ](#bkmrk-installation)
- *Installation via app/code*
- *Installation via Composer*
2. [*Configuration Settings for Distance Based Shipping*](#bkmrk-configuration-settin)
- *Order Tags Logs*
- *Order Tags Grid*
- *General Settings*
3. [*Shipping Cost*](#bkmrk-shipping-cost)
4. [*Pick Store / Website Address from*](#bkmrk-pick-store-website-address-from)
### Installation
- **Installation via app/code:** Upload the content of the module to your root folder. This will not overwrite the existing Magento folder or files, only the new contents will be added. After the successful upload of the package, run below commands on Magento 2 root directory.
```php
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
```
- **Installation via Composer:** Please follow the guide provided in the below link to complete the installation via composer.
[https://docs.scommerce-mage.com/magento-2-extensions/installation-via-composer/installation-via-composer](https://docs.scommerce-mage.com/magento-2-extensions/installation-via-composer/installation-via-composer)
### Configuration Settings for Distance Based Shipping
Go to **Admin > Stores > Configuration > Sales> Delivery Methods > Distance Based Shipping**
#### General Settings
- **Enabled Shipping Method –** Select "Yes" or "No" to enable or disable the module.
- **License Key –** Please add the license for the extension which is provided in the order confirmation email. Please note license keys are site URL specific. If you require license keys for dev/staging sites then please email us at .
- **Title -** Please enter the Title of Distance based Shipping.
- **Method Name -** Please enter the Method name of Distance based Shipping.
- **Shipping Cost -** The range is defined as: greater than or equal to "Distance From" and less than "Distance To".
- **Ship to Applicable Countries -** Select the applicable shipping destination(s).
- **Show Method if Not Applicable -** Select “Yes” or “No” to display the method when it is not applicable
- **Displayed Error Message -** Please enter the error message to be displayed
- **Sort Order -** Please enter the Sort order
- **Google Maps Api key -** Use a secure API key provided by Google to authenticate distance calculation requests via the Distance Matrix API.
- **Distance Unit -** Select whether to compare distances in miles or kilometers.
- **Pick Store / Website Address From -** **Select the method for sourcing the store address:**
- **Website Source**: Uses the address defined in the MSI configuration. *(Visible only when MSI is enabled.)*
- **General → Store Information**: Pulls the address from the store’s configuration settings.
- **Enter Address Manually**: Allows the admin to input latitude and longitude directly.
- **Enabled Debug -** Select “Yes” to enable debug mode, or “No” to disable it.
- **Filter Methods by Distance -** Select “Yes” to enable distance-based filtering, or “No” to disable it
- **Distance Threshold -** Please add the Distance Threshold.
- **Shipping Methods -** Select the shipping methods to hide when the store-to-customer distance exceeds the defined threshold.
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/iDHimage.png)
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/EIBimage.png)
#### Shipping Cost
Go to **Admin> Stores > Sales > Delivery Methods > Distance Based Shipping**
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/Jyfimage.png)
### **Shipping Method Configuration**
- **Enable this Method (Yes / No)**
- Turns this specific shipping method on or off within the distance-based filter.
- When set to **Yes**, the related configuration fields below become active.
- **Shipping Title**
- The user-friendly name shown to customers during checkout (e.g., "Standard Delivery").
- Helps customers differentiate between multiple shipping options.
- **Shipping Method Name**
- An internal name used for programmatic reference, logging, and in the admin panel.
- Not typically visible to customers.
- **Shipping Cost**
- The cost applied to this shipping method.
- Its calculation depends on the **Type** field (see below):
- Can be a fixed value (e.g., `5.99`).
- Or a percentage of the cart's subtotal (e.g., `5` for 5%).
- **Distance From**
- The **minimum** distance (in miles or kilometers) from the store for this method to be available.
- Defines the start of the valid range.
- **Distance To**
- The **maximum** distance (in miles or kilometers) from the store for this method to be available.
- Defines the end of the valid range.
- **Type**
- Determines how the **Shipping Cost** is calculated.
- **Fixed:** Applies the cost as a flat fee.
- **Percentage:** Calculates the cost as a percentage of the order's subtotal.
- **Show Method if Not Applicable (Yes / No)**
- **Yes:** The method will be displayed even if the customer is outside the distance range, but will show an error message.
- **No:** The method will be completely hidden if the customer is outside the distance range.
- **Displayed Error Message**
- The custom message shown to customers when "Show Method if Not Applicable" is set to **Yes** and they are outside the valid distance range.
- Example: "This shipping method is not available for your location."
- **Ship to Applicable Countries**
- Defines the geographical availability of the method:
- **All Allowed Countries:** Available to all countries your store ships to.
- **Specific Countries:** Limits the method to a selected list of countries.
- **Ship to Specific Countries**
- A multi-select list to choose which countries this shipping method is available to.
- This field only appears if "Ship to Applicable Countries" is set to **Specific Countries**.
- **Sort Order**
- A number that determines the order in which this method appears in the checkout list compared to other methods.
- Lower numbers (e.g., 0, 1) are displayed first.
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/ugcimage.png)
When a customer enters an address on the checkout page, the system calculates delivery cost based on the distance from the origin address and the distance ranges configured are as follows: -
- **Zone 1: 0–10 km**: Delivery cost is 2
- **Zone 2: 11–20 km**: Delivery cost is 10
- **Zone 3: 21–90 km**: Delivery cost is 10
Refer to the screenshot below to validate the shipping methods based on calculated distance fall under the above configured distance ranges: -
### **Frontend images based on above configured distance ranges:**
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/ZvPimage.png)
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/kOAimage.png)
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/z0Uimage.png)
#### Pick Store / Website Address from
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/oGTimage.png)
**Website Source -** To add a website source, navigate to: **Admin > Stores > Configuration > Sources** From there, you can enter the required source details.
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/Jfdimage.png)
**General - Store Information** – Displays the store address as configured in the **Store Settings** section. This information is automatically pulled from the predefined store configuration. To configure, navigate to **Admin > Stores > General > Store Information** and enter the store address. This address will be used as the source (origin) for distance-based calculations.
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/ugcimage.png)
**Enter Address Manually –** Enables administrators to input geographic coordinates—**latitude** and **longitude**—directly, bypassing automated location detection or map-based selection.
To configure this manually, navigate to: **Admin > Stores > Sales > Delivery Methods > Distance-Based Shipping** From there, enter the desired latitude and longitude values. These coordinates allow Google Maps to accurately detect and associate the location for distance-based calculations.
[](https://docs.scommerce-mage.com/uploads/images/gallery/2025-08/oIBimage.png)
If you have a question related to this extension please check out our [**FAQ Section**](https://www.scommerce-mage.com/magento-2-order-tagger.html#customfaq) first. If you can't find the answer you are looking for then please contact [**support@scommerce-mage.com**](mailto:core@scommerce-mage.com)**.**