Chapter 20: Geographic Locations & Delivery Coverage Zones
Configuring multi-national delivery zones, 1-click cloud state synchronization, ISO Alpha-2 country standards, interactive province management, and dynamic checkout address cascades.
1-Click Online State Sync
Automated integration with global geo-APIs (countriesnow.space) to ingest hundreds of states/provinces in seconds.
ISO-2 Flag Standards
Standard 2-letter uppercase country codes (BD, US, GB, CA, DE, AU) enabling automatic flag rendering and payment gateway compliance.
Interactive State Tags
Visual, removable state badges with overflow counters (+X more) for frictionless regional delivery zone curation.
Geographic Hierarchy & Commerce Architecture
Delivery accuracy is the foundation of successful eCommerce fulfillment. The MartX Locations & Coverage Engine provides a robust relational hierarchy connecting Country > State / Province / Division > Shipping Couriers. This ensures that customers at storefront checkout only see valid shipping destinations, allowing store managers to define exact coverage boundaries and avoid costly out-of-coverage delivery failures.
• Admin Dashboard > Administration & Settings > Locations > Add Location
20.1 Location Directory & Interactive State Tag Management
The Location Management master console displays an interactive inventory of all supported countries, their ISO regional codes, and active delivery states. The interface incorporates real-time search and an integrated Sync States From Online cloud tool.
Master Location Table Schema & UI Controls
| Column / Control | Component Type | Operational Functionality |
|---|---|---|
| All Locations (5) | Dynamic Counter | Header telemetry badge indicating the total count of active operational countries configured in the MartX database. |
| Search Input | Debounced Filter | Instant search query matching Country Name, ISO Country Code, or individual State/Province names without full page reloads. |
| COUNTRY | Data Identifier | Displays the formal country name preceded by a standardized globe/flag icon (e.g., Germany, Australia, Canada, United Kingdom, United States). |
| STATES Badges | Interactive Chips | Visual tag chips (e.g., New York ×, California ×) representing active states. Clicking the cross icon (×) dispatches an instant deletion request to purge that specific region from storefront checkout. |
| +X More Counter | Overflow Popover | Prevents table row inflation when a country has dozens of states (e.g., US has 50 states). Displays the primary regions inline and groups remaining areas in a clean overflow counter. |
| Action Dropdown (⋮) | Contextual Menu | Provides direct operations to edit country metadata, view full regional breakdowns, or delete the country and its child state relations. |
20.2 Automated 1-Click Online State Synchronization
Manually typing dozens of states, provinces, or prefectures for multiple countries is tedious and error-prone. MartX incorporates a built-in 1-Click Online State Synchronization Engine powered by the global countriesnow.space API.
The Cloud Sync Execution Pipeline
Select Target Country
In the right-hand Sync States From Online card, choose any registered country from the dropdown list (e.g., Germany, Canada, Australia).
Trigger Cloud Ingestion
Click Sync States. The backend dispatches a secure HTTP POST request to https://countriesnow.space/api/v0.1/countries/states with the country payload.
Deduplicated Ingestion
The repository processes the API response via State::firstOrCreate(), inserting only non-existing states while preserving existing IDs and courier mappings.
Merchant Benefits: Automated vs Manual Data Entry
100% Zero Manual Typing
Instead of spending hours manually researching and typing 50 US states, 16 German Bundesländer, or 10 Canadian provinces, simply select the country from the dropdown and click Sync States.
Smart Duplicate Prevention
The cloud sync engine automatically checks existing records before saving. You can safely trigger the sync button anytime without creating duplicate regions or disrupting active shipping rules.
Zero Duplication Guarantee
Because synchronization relies on firstOrCreate based on unique compound keys (country_id + name), you can click Sync States multiple times without creating duplicate entries or corrupting customer shipping addresses.
20.3 Manual Country & State Provisioning Console
For custom geographic boundaries, territories, or local administrative divisions that may not exist in standard global registries, MartX offers a dual-card Add New Location provisioning screen.
Card 1: Add Country
Create a new sovereign country or independent delivery territory:
BD, US, GB, CA, DE). Stored in uppercase.
Dispatches to
POST /admin/location/country.
Card 2: Add State (Manual)
Manually add a specific division, province, county, or city to an existing country:
Dispatches to
POST /admin/location/state.
20.4 Storefront Checkout Cascades & Courier Integration
The locations configured in this module directly govern the checkout experience on your MartX storefront. When a shopper places an order, the address selection flow executes a dynamic, responsive AJAX cascade.
Checkout Address Cascade Flow
1. Customer Selects Country
The shopper chooses their delivery country from your store's supported destination list.
2. Instant State Loading
The State/Province dropdown updates instantly with only the active regions you have enabled.
3. Accurate Shipping Rates
Delivery couriers and regional shipping costs (Chapter 10) calculate automatically in real time.
| Storefront Stage | Shopper Interaction | Merchant Control & Operational Impact |
|---|---|---|
| Country Selection | Selects delivery country at checkout | Only countries activated in Location Management appear in the storefront dropdown, preventing orders from unsupported nations. |
| State Cascading | Selects regional province, state, or division | Automatically filters available provinces based on your active state tags, ensuring customers provide verified regional shipping addresses. |
| Shipping Cost Calculation | Views available couriers and rates | Pairs directly with Chapter 10: Couriers & Shipping Costs to quote exact regional delivery fees before final order payment. |
20.5 International Expansion & Coverage SOP
Follow these enterprise standard operating procedures when expanding your eCommerce store to new international markets or restricting shipping during regional logistics disruptions.
SOP: Launching a New International Market
- Verify shipping courier rates and lead times with DHL, FedEx, or local logistics partners (see Chapter 10: Couriers & Shipping Costs).
- Navigate to Add New Location and register the destination country with its official ISO Alpha-2 code (e.g.,
FRfor France,JPfor Japan). - Return to Location Management and use Sync States From Online to automatically import all provinces or prefectures in one click.
- Assign relevant shipping costs in the Courier configuration. Customers in that country can now place orders immediately.
SOP: Restricting Affected Delivery Zones
- In the event of regional weather disruptions, strikes, or courier suspensions in a specific province (e.g., remote territories), find the country row in the master table.
- Click the small
×button on the specific state badge (e.g.,Bavaria ×). The state is removed from checkout eligibility instantly. - Checkout attempts from that region will display a helpful customer notice: "We currently do not ship to the selected state."
- Once logistics resume, re-add the state manually in 10 seconds via Add State (Manual).