Geographic Operations Chapter 20 of 22

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 Navigation Paths:
• Admin Dashboard > Administration & Settings > Locations > All Locations
• 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.

Admin Panel — Location Management: Country & State Directory
Locations Sync
MartX Location Management Directory and Cloud Sync Panel
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
1
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).

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

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

Admin Panel — Provision New Location: Dual-Card Country & State Creator
Territory Creator
Add New Country and Add State Manual Form
Card 1: Add Country

Create a new sovereign country or independent delivery territory:

Official English name of the country.
2-letter ISO 3166-1 alpha-2 code (e.g., BD, US, GB, CA, DE). Stored in uppercase.
Button: + Add Country
Dispatches to POST /admin/location/country.
Card 2: Add State (Manual)

Manually add a specific division, province, county, or city to an existing country:

Select the parent country to attach the new state to.
Specific administrative subdivision (e.g., Dhaka, Chittagong, Bavaria).
Button: + Add State
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
  1. Verify shipping courier rates and lead times with DHL, FedEx, or local logistics partners (see Chapter 10: Couriers & Shipping Costs).
  2. Navigate to Add New Location and register the destination country with its official ISO Alpha-2 code (e.g., FR for France, JP for Japan).
  3. Return to Location Management and use Sync States From Online to automatically import all provinces or prefectures in one click.
  4. 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).
Documentation
⚡ 3-Minute Quick Start 1. Introduction & Overview 2. Server Requirements 3. Installation Guide 4. License Activation 5. Dashboard Telemetry 6. Media Manager 7. Catalog Management 8. Products Management 9. Orders & Fulfillment 10. Couriers & Shipping Costs 11. Coupons & Marketing 12. Payment Gateways 13. Theme Layouts Hub 14. Navigation & Mega Menus 15. Sliders & Banners 16. Pages, FAQ & About 17. Blogs & Editorial 18. Reviews & Messages 19. Team Members & Staff Roles 20. Locations & Coverage 21. System Settings Hub 22. Web Cron & FAQs 23. Extra Security & Speed Boost